13 Macros

Curly braces should be escaped with a backslash (i.e., \{ and \}), as they usually mark macros:


NOTE: Macros cannot cross paragraph boundaries, i.e., they must not contain empty lines. Using newlines in a macro argument is useless, as the macro text will be collapsed to one single line.

NOTE: These aren’t macros in the sense of read-time expansions/replacements. They are called macros here because the (original) term commands is now used for #CMD type of commands only.

NOTE: If the macro name is unknown, a clip or a variable will be used instead. The order is: macros > clips > variables.

NOTE: Some macros parse their arguments, which then can contain other macros – e.g., list and item. “Parsing” is done with a simple nested regular expression. This appears to work quite well but could yield unintended results in some situations. The maximum of nested macros currently is 5 (which should really enough due to the primitivity of the macro language). If you want more (e.g., 10), add this to your config file:


Example 13.1: Macro written in Ruby

#Ruby context=ruby <<--
class Deplate::Macro::Test < Deplate::Macro
    register_as 'test'
    def setup(text)
        @elt = @deplate.parse(@container, '<' + text + '>')

Bla {test: [1 
        {test: 2 
            {test: 3 
                {test: 4}
        inner bla
        {test: a 
            {test: b 
                {test: c 
                    {test: d}


Bla <[1 <2 <3 <4>>> inner bla <a <b <c <d>>>>]> Bla

NOTE: You could run into problems if an macro argument contains unbalanced curly braces. It should work by preceding them with a backslash, but …

13.1 Getting or setting data about the document

Attributes: {attrib: KEY=VALUE …}
Change the previous particle’s (inline element) attributes; this command does on a text level what #OPT does for block elements
Clips, variables: {get [default=TEXT]: ID}, {get id=ID [default=TEXT]}
see also 11.11; access “clips”, e.g. the document’s author: {get: author}
Counters: {counter [depth=N] [delta=N]: NAME}
access a counter; see 12.5 for an example
Element properties: {eprop …}
Set the container element’s properties (as if using the #PROP command).
Document variables: {var: ID}
access document variable. See also the comments below on the arg macro. The difference between var and arg is that the var macro returns a value in a format can read.
Element options: {opt: ID}
access element (paragraph, table etc.) options
Retrieving variables : {arg: NAME}
Retrieve an argument (used in DefRegion or similar)
  • Variables can also be accessed as in {varname} which will expand to {arg: varname}. {varname!} will expand to {var: varname}. Thus, {varname capitalize!} is equivalent to {arg capitalize!: varname}.
  • The xarg macro is a variant of this that can be used to retrieve preformatted text.
  • Synonyms: val, xval
  • If the . allow flag is set, the NAME may have the form NAME[METHOD] to send methods to an object.
  • Options:
    Join the values of strings and hashes
    values! keys!
    Return a hashes values of strings
    Replace a pattern (the ‘/’ is an arbitrary separator in this example; this can be any character)
    Character translation
    Put the text in upper case letters
    Put the text in lower case letters
    Capitalize the text
    Escape some characters with a backslash
    Escape backslashes with a backslash
  • The execution order of the text transformations arguments is fixed: sub > tr > upcase > downcase > capitalize
Localized messages: {msg: TEXT}
Insert a localized message (can be used in templates).

13.2 References, labels, index

Anchors: {anchor: NAME}
Inserts an anchor at this very position; this should only used in inline position within a list item, a paragraph etc. It should be also used within lists or similar compound elements.
  • Synonyms: label, lab
Comments: {cmt: TEXT}
insert an empty string
Index: {idx: NAME}
Inserts an index at this very position; this should only used in inline position within a list item, a paragraph etc. It should be also used within lists or similar compound elements.
Reference: {ref [prefix=TEXT] [p!]: ANCHOR}
insert a reference to an anchor
Reference to page
Prepend this text to the reference (default: non-breaking space)

13.3 Bibliography

Citation: {cite [p=PAGE] [n=NOTE] [np!] [y!]: ID1[;ID2…]}
output depends on the formatter
No parentheses
Year only
The page number
A note to be inserted before the citation (but within the parentheses)

13.4 Textstyles

Code: {code: CODE} or {'CODE}, or {verb: CODE}
the same as ''CODE''
Emphasized text: {_TEXT} or {em: TEXT} or {emph: TEXT}
emphasized text (the same as __TEXT__)
Plain text: {plain: UNPARSED TEXT} or {\UNPARSED TEXT}
insert the text without intepreting deplate markup
Subscript: {sub: TEXT} or {,TEXT}
Put TEXT in subscript
Superscript: {super: TEXT} or {sup: TEXT} or {^TEXT}
Put TEXT in superscript
Stacked: {stacked:{:SUPER}{:SUB}}} or {%{:SUPER}{:SUB}}
Print SUPER on top of SUB (the HTML formatter uses css inline tables, which are displayed as expected with Firefox/Mozilla)
Text: {text: TEXT} or {:TEXT}
Parsed TEXT. This macro can also be used to attach a style to some inline text.
Mark 1st occurrence: {~text} {mark1st: text}
Mark TEXT, when the text is inserted for the first time. If the variable mark1stStyle is defined, this style will be used. Otherwise, the string’s first occurrence will be printed in upper case letters. Arguments
Text used for lookup
Mark other occurrences with this style
always!, anyway!
Always mark as 1st occurrence, even if it isn’t.
Case: {downcase: TEXT} {upcase: TEXT} {capitalize: TEXT}
Change TEXT’s case

13.5 Dynamic text, particles

Date: {date: [format string|now|time|today|month|year]}
the format string uses ruby’s strftime method.
Footnote: {fn: ID} or {fn id=ID: TEXT}
The first form refers to a footnote defined by a Fn or Footnote region. The second form defines the footnote inline. The output depends on the formatter. The footnotes generated by the html formatter are compatible with OpenOffice.
Images: {img [IMG arguments]: FILE}
insert an image; takes the same options as IMG (see 12.5)
Inline LaTeX: {ltx id=ID [other Inlatex options]: LATEX CODE}
Insert small pieces of latex code.
Pagenumber: {pagenumber [hd!]: [TEXT]}
Returns the current page number. The result depends on the formatter. TEXT is appended to the pagenumber if the result is non-empty.
Insert nothing
Insert \thepage if the macro isn’t used in a header region (the optional hd! argument)
LaTeX + koma
Insert \pagemark
Small lists: {list type=[ol|ul|dl]: ITEMS}
A convenience macro for inlining small lists into other elements. Items can defined with the following two macros:
  • {item: TEXT}
  • {term id=TERM: TEXT}
e.g., {ins fmt=html: &lt;&lt;}
Mathematical text: {math [block!]: LATEX FORMULA}
insert a small mathematical expression in latex syntax
  • Synonyms: $
  • If the block! argument is supplied, the formula is wrapped in \[formula\] instead of $formula$.
  • See also 9.2.14 and 11.8.
  • You can set the variable mathPrelude in order to prepend some LaTeX code to all mathematical formulaes
Newline: {nl}
start a new line
Ruby code: {ruby [context=CONTEXT] [alt=ALTERNATE OUTPUT]: RUBY CODE}
  • if the evaluation of ruby code is disabled, the text given in the alt option or an empty string will be inserted
  • a sequence of ruby commands must be separated by semicolons
  • for the CONTEXT argument please see 11.14

Example 13.2: Macros

Foo bar{fn: x} foo bar.

#Fn: x <<EOFN
    Ceci n'est pas une note.

Bar is bar.

Foo is foo (see also{ref: bar}).

#BIB: deplate.bib
Mynona's{cite y! n=e.g.,: mynona:p1} real name was Salomo Friedlaender.

% You can find the bibliography down below. The command is commented out 
% in order not to confuse nervous docbook tools.
% #MAKEBIB plain!: cbib-apa-1

This line{cmt: here} contains a comment.

{date: today}

{ruby alt=ruby disabled: 1 + 1}

An inline {img rotate=90 h=40: linked} image (which is rotated in LaTeX 

Test ({ltx: $\sum_{i=n}^{n} x_{i}$}) the ltx macro.

Text formatting:
Foo{,bar & bar} is foo, but bar{^foo & foo} is bar.
Foo {\__with__} or {plain: ''without''} bar.

{~Tom} says: "My name is {~Tom}."

{upcase: Foo bar}, {downcase: Foo bar}, {capitalize: Foo bar}.

x{%{:2}{:a}} = 1

#IF: fmt!=latex
Small lists (this example doesn't work in latex):
| {list: {item: foo} {item: bar}} \
| {list type=dl: {term id=Foo: Foo is foo} {term id=Bar: Bar is bar}} \
| {list: {item: here} {item: there}} \
| {list type=dl: {term id=Here: Here is here} {term id=There: There is there}} \

If you allow ".", you can could do something like this: This is the 
paragraph with the id ''testParagraph1''.
#OPT: id=testParagraph1

The element with id=testParagraph1 is a {let t=object(id=testParagraph1): 
{arg asString!: t.class}}.

#VAR: varname=Lala
#CLIP id=theSinger: __Maestro__ Maximo
{varname} is foo. {arg: varname} is foo.

{varname!} is bar. {var: varname} is bar.

{theSinger} sings {varname!}.


Footnotes: Foo bar2 foo bar.

Reference: Bar is bar.

Foo is foo (see also 13.5).

Citation: Mynona’s (e.g., 1980) real name was Salomo Friedlaender.

Comments: This line contains a comment.

Date: 29. Nov 2008

Ruby: 2

Image: An inline linked image (which is rotated in LaTeX output).

LaTeX: Test ($sum_{i=n}^{n} x_{i}$) the ltx macro.

Text formatting: Foobar & bar is foo, but barfoo & foo is bar. Foo __with__ or ''without'' bar.

TOM says: “My name is Tom.”

FOO BAR, foo bar, Foo bar.

x2a = 1

Small lists (this example doesn’t work in latex):

  • foo
  • bar
Foo is foo
Bar is bar
  • here
  • there
Here is here
There is there

If you allow “.”, you can could do something like this: This is the paragraph with the id testParagraph1.

The element with id=testParagraph1 is a Deplate::Element::Paragraph.

Lala is foo. Lala is foo.

"Lala" is bar. "Lala" is bar.

Maestro Maximo sings "Lala".

2Ceci n’est pas une note.

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
11 Regions
12 Commands
13 Macros
13.1 Getting or setting data about the document
13.2 References, labels, index
13.3 Bibliography
13.4 Textstyles
13.5 Dynamic text, particles
14 Skeletons
15 Variables and options
16 Internals
17 Extending deplate
18 Bibliography
19 Index
About this page