11 Regions

The text marked by a region is interpreted according to the region’s rules. The text could be normal deplate source, but it could also be ruby code, LaTeX, or whatsoever.

Check for end pattern:

#Type [OPTIONS] <<----
Text ...
----

Match until next empty line:

#Type [OPTIONS] <<
Text ...

Deprecated:

#Type [OPTIONS]:
Text ...
#End

This form can’t be nested.

“Type” being one of:

  • Abstract
  • Code
  • Define
  • Doc, Var
  • Footnote, Fn
  • For
  • Header, Footer
  • Img
  • Inlatex, Ltx
  • Native or the name of the chosen formatter
  • Quote
  • Set
  • R (tables)
  • Region (generic)
  • Ruby
  • Drop, Swallow, Skip
  • Table
  • Verbatim, Verb
  • Write

11.1 Abstract

Example 11.1: Abstract

#Abstract <<EOA
''Deplate'' is ruby script for converting wiki-like markup to latex, 
html, or "html-slides". The markup was originally based on the 
emacs-wiki mode.
EOA

Output:

Deplate is ruby script for converting wiki-like markup to latex, html, or “html-slides”. The markup was originally based on the emacs-wiki mode.

11.2 Code

This region should be used for displaying source code. Depending on the your use of the corresponding highlighter modules (see 9.2.4,  9.2.3) and its capabilities, the source code will be highlighted.

Options:

id
Allow deplate to cache the formatted output
syntax
The code’s syntax
style
The style that should be used for highlighting

Example 11.2: Code, syntax highlighting

#Code id=Foo syntax=ruby <<---
class Foo
    # Return two times x
    def bar(x)
        x * 2
    end
end
---

Output:

class Foo
    # Return two times x
    def bar(x)
        x * 2
    end
end

NOTE: These corresponding highlighter modules rely on external programs. You thus have to allow deplate to run programs, e.g. by using the -X command line switch.

11.3 Define: DefRegion, DefCommand, DefMacro, DefElement, DefRegionN, DefCommandN, DefMacroN

This is still somewhat experimental and doesn’t always work right.

These regions provide a deplate only way to define simple macros or rather mini templates. So you don’t have to know ruby in order to perform macro/template-expansion kind of stuff.

These regions come with several synonyms:

DefRegion
DefineRegion, Defr
DefCommand
DefineCommand, Defc
DefMacro
DefineMacro, Defm
DefElement
DefineElement, Defe
DefRegionN
DefineRegionN, Defrn
DefCommandN
DefineCommandN, Defcn
DefMacroN
DefineMacroN, Defmn

The anonymous argument will temporarily (during template expansion) assigned to the document option @body, which can be accessed by #VAR, {var}, #ARG, or {arg}. The doc command/macro insert the argument as plain text, while the arg command/macro parses the argument.

When choosing argument names, be aware that they are passed as document options (see 15.1) and that some of these arguments (e.g., id, fmt, noFmt, if) are implicitely evaluated by deplate. The unnamed arguments @note and @body are assigned by deplate.

Macro templates are parsed as normal templates first (see 5.5). As a consequence, macro templates may contain #IF commands and the like.

#Region NAMED_REGION_ARGUMENTS NAMED_TEMPLATE_ARGUMENTS: @note <<-
@body
-
#Region NAMED_REGION_ARGUMENTS NAMED_TEMPLATE_ARGUMENTS <<-
@body
-

#COMMAND NAMED_COMMAND_ARGUMENTS NAMED_TEMPLATE_ARGUMENTS: @body
#COMMAND NAMED_COMMAND_ARGUMENTS NAMED_TEMPLATE_ARGUMENTS
#COMMAND: @body

{macro NAMED_MACRO_ARGUMENTS NAMED_TEMPLATE_ARGUMENTS: @body}
{macro NAMED_MACRO_ARGUMENTS NAMED_TEMPLATE_ARGUMENTS}
{macro: @body}

Example 11.3: Define a new region

#DefRegion id=ThingsIHaveTo <<--
Things I have to {arg default=eat: do}:
#XARG: @body
--
#DefMacro id=thing args=@body <<--
__{xarg: @body}__
--
% The ''args'' argument make these keys mandatory!
#DefCmd id=THING args=name @body <<--
| {thing: {xarg: name}} | {xarg: @body} |
--

#ThingsIHaveTo do=buy <<---
#THING name=Apples: 1kg
#THING name=Peaches: 2kg
---

Output:

Things I have to buy:

Apples 1kg
Peaches 2kg

The examples in this document were printed with this DefRegion:

#DefRegion id=Example <<--
Example:
#WITH arg=@body: Verb

yields{arg default="": note}:

#ARG: @body
--

Example 11.4: Example region

#Example note=" an example" <<---
__Yes__, this is an example of using the #Example region.
---

Output:

Example 11.5: Example region

__Yes__, this is an example of using the #Example region.

Output an example:

Yes, this is an example of using the #Example region.

This regions displays its body twice: first wrapped in a #Verb and then properly parsed and formatted.

Example 11.6: Literate programming

This can also be used for some kind of cheap literate programming experience.

#DefRegion id=Source @args=file <<--
\#WITH arg=@body: Write append! file={xarg: file}
\#WITH arg=@body: Code id={xarg:id}
--

The #WITH command is escaped with a backslash so that the template input filter, which pre-processes the body, doesn’t complain about an unknown region (as the template input filter doesn’t allow #WITH commands).

This region could be used as follows:

#VAR: codeSyntax=ruby codeStyle=tomacs

So, you would really like to define a new class. Now?

#Source id=classFooOpen file=foo.rb <<
class Foo

And then maybe even add a method?

#Source id=methFoo_test file=foo.rb <<
    def test(a)
        p a * 2
    end

Well, it's really up to you.

#Source id=classFooEnd file=foo.rb <<
end

The command

deplate --allow=w,W -m code-gvim71 test.txt

would then create two files (test.html and foo.rb). In this simple version the generated documentation and source files would reside in the same directory though. Before re-running the command, you’d have to clear the output directory.

11.3.1 Elements

Within some limitations, you can also define your own elements.

Example 11.7: Define an element

#DefElement rx=(\\s+)\\[ \\]\\s+(.*) <<--
{arg: 1}+ {arg: 2}
{arg: 1}#OPT: style=todo
--
#DefElement rx=(\\s+)\\[x\\]\\s+(.*) <<--
{arg: 1}- {arg: 2}
{arg: 1}#OPT: style=todo
--
    [ ] Something I should do 
        but haven't done yet.
        [ ] Something else
    [x] Something I did,
        maybe yesterday.

Output:

  • Something I should do but haven’t done yet.
    • Something else
  • Something I did, maybe yesterday.

11.3.2 Particles

You can also define particles if you really want to.

Example 11.8: Define a new particle

#DefParticle: \^(\w+?)\^ <<--
{sup: {arg: 1}}
--
Test: x^2^

Output:

Test: x2

11.3.3 Native templates

The *N variants of these regions define “formatter native” templates.

Example 11.9: Insert text literally

#IF: fmt=~html
#DefRegionN id=Pairs <<---
<p><em>{arg: name}</em></p>
<table>
#ARG: @body
</table>
---
#DefCommandN id=LISTPAIR <<---
<tr>
{arg: @body}
</tr>
---
#DefMacroN id=pair args=name @body <<---
<td><em>{arg: name}</em></td><td>{arg: @body}</td>
---

#Pairs name=A list of pairs <<---
#LISTPAIR: {pair name=<test>: <Foo>}
#LISTPAIR: {pair name=<native>: &}
#LISTPAIR: {pair name=<define>: <Bar>}
---
#ELSE
Sorry, the example is defined for HTML output only.
#ENDIF

Output:

A list of pairs

<test><Foo>
<native>&
<define><Bar>

11.4 Doc, Var

Defining a document variable using the #Var can come handy in conjunction with #For. It’s important to understand that a variable defined by the #Var region is internally represented as an array (one entry per line). If you simply insert this array into a document, the result might not look like what you expected it to be. Also, if you write your own modules, using the #Var region is a convenient way to pass around information.

11.5 For

This region provides a simple way of looping through lists.

Arguments:

id
The doc variables the values should be assigned to.
sep
The list separator (if the argument is a string)
var
The document variable, which holds the list (if this isn’t defined, the text after the colon will be used)

Example 11.10: For

#Var: Fruits:
1kg, apples
2kg, peaches
#End

#For id=listentry doc=Fruits <<--
\#For id=kg,fruit sep=, doc=listentry:
I would like to buy \{arg: kg} of \{arg: fruit}.
#End
--

Output:

I would like to buy 1kg of apples.

I would like to buy 2kg of peaches.

It is necessary to escape the inner #For region and the arg macros with backslashes, because the body is passed through the template filter. You can prevent this by using the noTemplate! argument or by setting the legacyFor1 variable.

11.6 Header, Footer

The argument to these regions is either a paragraph or a table with up to three columns. The result of the header and footer region depends on the formatter.

HTML
Insert the argument at the top/bottom of the document
LaTeX
Ignore footer, add the header using \markright{}
LaTeX + koma module
Use koma’s scrpage2 package to format the header and the footer; with the koma module these regions take some optional arguments
  • center, right (only if the text is a paragraph; the default is to put the header/footer in the left column)
  • linesep=\d+, linesep=\d+pt, linesep! (defaults to 0.4pt)
    • or use the abbreviation “sep”

See also notes on the pagenumber macro.

11.7 Img

deplate provides support for including graphics generated “on the fly” by other programs.

Synonyms
Image, Fig, Figure

Options:

id
the basis for the filenames (RECOMMENDED, default: deplatxImgAuto%02d); if you don’t provide an id, deplate uses an automatically generated one. Anyway, if you make changes to the document, it’s possible that the generated graphics get messed up
sfx
the graphic file’s suffix

Argument (after the colon): PROGRAM_NAME COMMANDLINE_OPTIONS …

  • PROGRAM_NAME is the program name known to deplate, currently
    • dot
    • neato
    • R
      • Note: Options for the R devices can be defined as arguments to the region. In the form “DEV_OPTION” the option is specific to a chosen device (e.g. “png_width=700”). In the form “_OPTION”, it is applicable to all devices (e.g. “_pointsize=10”). This is necessary as some devices expect dimensions to be given in inches, other in pixels. Please refer to the R manual to find out which options are applicable.
  • COMMANDLINE_OPTIONS are pasted somewhere into the command call – how this exactly happens depends on the calling method

The region Img returns an object of the same type as the command IMG (see 12.5). All arguments are passed on to the resulting object.

Example 11.11: Image created with dot

Using ''dot'':

#Img id=dot_example: dot <<---
digraph structs {
    node [shape=record];
    struct1 [shape=record,label="<f0> A|<f1> B|<f2> C"];
    struct2 [shape=record,label="<f0> D|<f1> E"];
    struct3 [shape=record,label="<f0> F|<here> G"];
    struct1:f1 -> struct2:f0;
    struct1:f2 -> struct3:here;
}
---
#OPT fmt=latex: w=6cm
#CAP: Example based on the dot manual

Using ''R'':

#Img id=r_geyser: R <<---
attach(geyser)
truehist(duration, nbins=20, xlim=c(0.5, 6), ymax=1.2)
lines(density(duration, width="nrd"))
---
#OPT fmt=latex: w=6cm
#CAP: Example plot based on Venables/Ripley{cite y!: mass4}

Output:

Using dot:

Figure 11.1: Example based on the dot manual

dot__example

Using R:

Figure 11.2: Example plot based on Venables/Ripley (2003)

r__geyser

11.8 Inlatex, Ltx

deplate contains primitive support for including LaTeX as graphics in non-latex documents. This requires latex, dvips, and ghostscript to be installed.

Synonyms
Ltx

Options:

id
the basis for the filenames (RECOMMENDED, default: deplateLtxAuto%02d); if you don’t provide an id, deplate uses an automatically generated one. Anyway, if you make changes to the document, it’s possible that the generated graphics get messed up
sfx
the suffix/device for the graphic file (default: jpeg)
rx
the resolution of the graphic file (default: 140)
type
“fig” (the default) or “table”

All the options if #IMG 12.5 apply, too.

By default the following packages are loaded:

  • amsmath
  • amsfonts
  • amssymb
  • mathabx

If the LaTeX formatter was chosen anyway, the source is inserted literally in the output document.

See the ltx macro 13.5 for an alternative for inserting smaller pieces of LaTeX-code.

The id is the basis for the filenames being used during conversion. The following files are generated:

  • by deplate: FILE.tex
  • by latex: FILE.dvi + auxiliary files
  • by dvips: FILE.ps
  • by ps2ppm: FILE.%02d.SFX
    • this depends on the sfx option

Lines that match /^\\(usepackage|input)(\[.*\])?\{.+\}$/ are put in the prematter of the latex file, the rest is put in the body.

Lines ending with %%% are moved to the prematter too.

Example 11.12: Inline LaTeX

#Set: InlatexExampleClip <<EOC
#Inlatex inline! id=InlatexExample sfx=jpeg bh=27 bw=79 <<EOI
\usepackage{graphicx}
$\sum_{i=n}^{n} \rotatebox{90}{$x_{i}$}$
EOI
EOC

This is a test ({get: InlatexExampleClip}) of a clipped Inlatex region 
as an inline graphic.

#Inlatex id=InlatexExampleXY <<-----
\usepackage[all]{xy}
\parbox{5cm}{
\xymatrix{
U \ar@/_/[ddr]_y \ar@/^/[drr]^x
\ar@{.>}[dr]|-{(x,y)} \\
& X \times_Z Y \ar[d]^q \ar[r]_p
& X \ar[d]_f \\
& Y \ar[r]^g & Z }
}
-----
#CAP: An example from the xypic-user guide

Output:

This is a test ( InlatexExample.01) of a clipped Inlatex region as an inline graphic.

Figure 11.3: An example from the xypic-user guide

InlatexExampleXY.01

11.9 Native

Example 11.13: “Native” text

#Native fmt=html <<EON
<p>&lt;native&gt; html</p>
EON
#Native fmt=latex <<EON
Pure LaTeX. $\sum_{i=n}^{n} x_{i}$
EON

Output(depending on the formatter):

<native> html

11.10 Quote

Synonyms: Qu

Options:

long!
Prepare a long quotation

Example 11.14: Quotations

#Quote <<---
As I said earlier ...
---

Output:

As I said earlier …

11.11 Set, Get

There are two ways of storing text for later use: clips and variables. Clips should be used for moving around parsed text within the document. Variables should be used for passing text to macros, commands etc.

The Set region and the SET command can be used to store clips. They differ in that the region results in an array of (block) elements and the command in a sequence of text particles/inline elements. This is important as there are also two corresponding ways to insert clips later on. The GET command, which is supposed to insert a block element, and the get macro, which works on the inline/text particle level.

Level Region Command Macro
Element Set GET
Text SET get

Example 11.15: Clip

#Set: clip <<EOC
| clipped | table |
#CAP: A clipped table
EOC

#GET: clip

#SET id=clippedText: clipped text
This is {get: clippedText}.

Output:

Table 11.1: A clipped table
clipped table

This is clipped text.

11.12 R generated tables

Include tables generated on-the-fly using R. The region takes one optional argument:

xtable
the result is a html table as formatted with xtable; this table won’t be used as such but it will be parsed and transformed into a deplate table; a library(xtable) statement is added to the R source
verb, verbatim
insert the result verbatim
drop, swallow
the R code doesn’t produce any interesting output (data sets, variables and the like should be saved in .Rdata)

The default is to generate a pseudo table from the verbatim R output.

Options:

skip=HEAD skip=HEAD,TAIL skip=,TAIL
Remove the first HEAD lines and the last TAIL lines from the R output
guess! scanTable!
Try to guess column borders

Example 11.16: Tables created with R

#R: drop <<---
data(tli)
x <- tli
save.image(compress=T)
---

#R: xtable <<---
fm1 <- aov(tlimth ~ sex + ethnicty + grade + disadvg, data=x)
fm1.table <- xtable(fm1)
print(fm1.table,type="html")
---
#CAP: An example from the xtable manual using the tli data set

#R <<---
summary(x)
---
#CAP: Summary of the tli data set

#R guess! <<---
summary(x)
---
#CAP: Summary of the tli data set (guessing cell borders)

The same inserted verbatim:
#R: verb <<---
summary(x)
---

Output:

Table 11.2: An example from the xtable manual using the tli data set
Df Sum Sq Mean Sq F value Pr(> F)
sex 1 75.37 75.37 0.38 0.5417
ethnicty 3 2572.15 857.38 4.27 0.0072
grade 1 36.31 36.31 0.18 0.6717
disadvg 1 59.30 59.30 0.30 0.5882
Residuals 93 18682.87 200.89
Table 11.3: Summary of the tli data set
     grade      sex    disadvg      ethnicty      tlimth    
 Min.   :3.00   F:51   NO :65   BLACK   :23   Min.   :17.0  
 1st Qu.:4.00   M:49   YES:35   HISPANIC:20   1st Qu.:69.0  
 Median :6.00                   OTHER   : 2   Median :80.0  
 Mean   :5.56                   WHITE   :55   Mean   :76.4  
 3rd Qu.:7.00                                 3rd Qu.:87.0  
 Max.   :8.00                                 Max.   :93.0  
Table 11.4: Summary of the tli data set (guessing cell borders)
grade sex disadvg ethnicty tlimth
Min. :3.00 F:51 NO :65 BLACK :23 Min. :17.0
1st Qu.:4.00 M:49 YES:35 HISPANIC:20 1st Qu.:69.0
Median :6.00 OTHER : 2 Median :80.0
Mean :5.56 WHITE :55 Mean :76.4
3rd Qu.:7.00 3rd Qu.:87.0
Max. :8.00 Max. :93.0

The same inserted verbatim:

     grade      sex    disadvg      ethnicty      tlimth    
 Min.   :3.00   F:51   NO :65   BLACK   :23   Min.   :17.0  
 1st Qu.:4.00   M:49   YES:35   HISPANIC:20   1st Qu.:69.0  
 Median :6.00                   OTHER   : 2   Median :80.0  
 Mean   :5.56                   WHITE   :55   Mean   :76.4  
 3rd Qu.:7.00                                 3rd Qu.:87.0  
 Max.   :8.00                                 Max.   :93.0  

11.13 Region

This is a generic region that can be used, e.g., to attach a style to some blocks. For HTML output, this would wrap the blocks in a div and define a class attribute.

11.14 Ruby

If a ruby region returns an array, its elements are treated as lines that are joined with “\n”.

Options:

plain!
reformat ruby’s output as a plain text paragraph (default)
verb!
put ruby’s output in a verbatim region
image=FILENAME
the result is a FILENAME to be included
native!
if neither the verb! nor the plain! option are given, consider the output to be already formatted.
context=ruby|deplate|self
sets the context and the method that are used to evaluate the code
ruby
use eval
deplate
use the current instance of Deplate::Core
self
use the invoking instance

The ruby code is currently simply evaluated in the context of the Deplate::Core.eval_ruby method. Inline ruby code can thus access a variable “caller” that refers to the instance, which invoked this evaluation. In future releases, the evaluation of ruby code will take place in a secured thread.

Example 11.17: Inline ruby

#Ruby context=deplate <<---
def a(x)
    return x*2
end

"Evaluated for #{@formatter.formatter_name}:
Ruby output: #{a(3)}"
---

Output:

Evaluated for htmlsite: Ruby output: 6

11.15 Drop, Swallow, Skip

Drop/Swallow/Skip (= don’t display) the text in this region. Process it nevertheless for possible side-effect – i.e., variables being set etc.

11.16 Table

This region takes some kind of text and transforms it into a table. Currently, only character/string separated tables are supported

Options:

sep
the cell separator regexp (default: “\t”)

Example 11.18: Create a table from tab-separated input

#Table sep=\\. caption=An example of an char separated table <<---
Foo.Bar
1.2
---

Output:

Table 11.5: An example of an char separated table
Foo Bar
1 2

11.17 Verbatim

The verbatim region inserts text as seen on the screen. Arguments:

wrap=N
The wrap margin

Example 11.19: Verbatim

#Verbatim wrap=10 <<---
Long long long long long long long line
---

Output:

Long long 
long long 
long long 
long line

11.18 Write

You have to set the “w” or “W” allow flag(see 4) in order to enable this region.

Write or append (append! option) an expanded template to a file.

If file is “-”, the body will be printed on STDOUT.

Example 11.20: Write something to a file

#Write file=test.txt <<---
Foo {arg: myvar} bar.
---
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
11.1 Abstract
11.2 Code
11.3 Define
11.4 Doc, Var
11.5 For
11.6 Header, Footer
11.7 Img
11.8 Inlatex, Ltx
11.9 Native
11.10 Quote
11.11 Set, Get
11.12 R generated tables
11.13 Region
11.14 Ruby
11.15 Drop, Swallow, Skip
11.16 Table
11.17 Verbatim
11.18 Write
12 Commands
13 Macros
14 Skeletons
15 Variables and options
16 Internals
17 Extending deplate
18 Bibliography
19 Index
About this page