# 13 Macros

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

{COMMAND [OPTIONS]: ARGS...}


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:

Deplate::Particle::Macro.build_rx(10)


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 + '>')
end
end
--

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


Output:

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]}
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=SEPARATOR
Join the values of strings and hashes
values! keys!
Return a hashes values of strings
sub=/pattern/replacement/
Replace a pattern (the ‘/’ is an arbitrary separator in this example; this can be any character)
tr=/pattern/replacement/
Character translation
upcase!
Put the text in upper case letters
downcase
Put the text in lower case letters
capitalize!
Capitalize the text
escape=“CHARACTERS”
Escape some characters with a backslash
escapebackslash!
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
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
p
Reference to page
prefix
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
np
No parentheses
y
Year only
p
The page number
n
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=TEXT
Text used for lookup
alt=STYLE
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.
HTML
Insert nothing
LaTeX
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}
Native text: {ins: LITERALLY INSERTED 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 Footnotes: Foo bar{fn: x} foo bar. #Fn: x <<EOFN Ceci n'est pas une note. EOFN Reference: Bar is bar. #bar Foo is foo (see also{ref: bar}). Citation: #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 Comments: This line{cmt: here} contains a comment. Date: {date: today} Ruby: {ruby alt=ruby disabled: 1 + 1} Image: An inline {img rotate=90 h=40: linked} image (which is rotated in LaTeX output). 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}} \
|
#ENDIF

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!}.


Output:

Footnotes: Foo bar2 foo bar.

Reference: Bar is bar.

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 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 Foo is foo Bar Bar is bar here there Here Here is here There 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.