15 Variables and options

15.1 Document variables

Basically, there are two ways to set a variable:

1. The #VAR command
2. In the deplate.ini file

User variables that have no special meaning should begin with an underscore. In restricted input mode, setting variables not beginning with an underscore is disabled.

Variables with all upper-case letter names should be considered as read-only variables. These are set by deplate and are not meant to be modified by the user.

Please see 15.6 to find out how to set variables for specific output formats only or depending on another variable’s value.

Define a baseUrl but only when generating multi-file html output:

#VAR fmt=~html(site|slides): baseUrl=http://deplate.sourceforge.net/ baseUrlStripDir=1

Define some stuff that should go to the html css section:

15.1.1 Pre-defined variables

env

The environment variables (HASH)

The following list mentions most variables that can be used to fine-tune some aspect of deplate’s behaviour. Please see 4, 5.3 or 12.1 to see how to set these variables.

15.1.2 General

authorSep

A string used to concatenate author names in some occasions (STRING, default: ;)

autoindex

Enable automatically adding entries to index (BOOLEAN, default: false)

autoBaseName

In multi-file output, deduce the output filename from the current input file (BOOLEAN, default: false)

autoFileNames

Enable automatic generation of file names based on the top heading for multi-file output (BOOLEAN, default: false)

auxiliaryDir

If defined, auxiliary files will be put into this subdirectory (STRING)

auxiliaryDirSuffix

If defined, auxiliary files will be put into a subdirectory named after the base name of the root file plus this suffix (STRING)

bibClickableCitation

Whether citations (eg in HTML output) are clickable hyperlinks (BOOLEAN, default=false)

bibStyle

Default bibliography style (STRING)

bibSepAuthors

The separator for author names (STRING, default=”; “)

bibSepLastAuthor

The separator for the last author name (STRING, default=”; “)

bibSepTwoAuthors

The separator between two author names (STRING, default=”; “)

bibSepName

The separator between prename and surname (STRING, default=”, “)

class

The document class; used in LaTeX (= document class) or HTML output (= CSS) (STRING)

codeLineNumbers

Display line numbers (BOOLEAN, default: false)

codeStyle

The default style used for formatting code regions; depends on the backend (STRING)

codeSyntax

The default syntax for #Code regions (STRING)

commentsShow

Display comments in the output (BOOLEAN = any comment or STRING = comments with this prefix/marker)

description

A short description of the document (STRING)

docBasename

The base name of the output document (STRING)

efilter

Include only elements in the output that are tagged with one of these tags. any matched untagged elements. (COMMA-SEPARATED LIST)

elementStyle

If set to ‘block’, the markup of styles changes. For LaTeX output, this make deplate use regions. You can set this for single elements too. (STRING)

embeddedTextRx

A regular expression matching embedded text (submatch $1) (REGULAR EXPRESSION)

embeddedVerbatim

The region name that will be used for text not matching embeddedTextRx (STRING, default: Verbatim)

encoding

The default encoding; dependent on the output format (STRING)

HTML

ISO-8859-1

LaTeX

latin1

XML

UTF-8

• In order to set the encoding do: #VAR: encoding=utf-8
• To set the encoding for HTML output only: #VAR fmt=html: encoding=utf-8

figureNumbering

How figures should be numbered (STRING)

flat, document

One counter for all figures

none

No numbering

section (DEFAULT)

Per section

floatAlign

The default alignment of floats; dependent on the output format (STRING)

headings

The headings style (STRING)

plain

Don’t number headings

homeIndex

The heading index that should be the home page in multi-file output (INTEGER; default: 0)

hyperHeading

If set and a heading has an url option attached, turn the heading into a hyperlink; if set to “full”, then heading is used as link text, which may result in invalid output; otherwise a button is attached to the heading (BOOLEAN or STRING)

hyperHeadingButton

The text for hyperlinked headings (STRING; default: ⇒)

imgSfx

The default suffix for images (STRING, default: png)

includeVars

The variables to be used for #INC commands (HASH)

indexwiki

If “no”, don’t autoindex extended wiki links (STRING)

• <+TBD+>This will be subject of change

inlatexPrelude

A string or array of strings that will be prepended to each inline LaTeX snippet

inlatexHeight, inlineLatexHeight

Define the h parameter of images generated by an inline LaTeX snippet (NUMBER)

itemizeMarkers

The markers for itemize lists (currently only used for plain text output) (COMMA-SEPARATED LIST)

ltxPointsize

The pointsize used for LaTeX snippets; this can be overridden by a per-element ‘pointsize’ argument; see also ps2imgRes (NUMBER, default: 10)

ltxSfx

The suffix of images generated by an inline LaTeX snippet (STRING, default: dependent on the output format)

keywords

The keyword to categorize the document; either an array of strings or a list separated by semi-colons

levelshift

Shift heading levels (NUMBER)

ltxPrelude

Like inlatexPrelude but used for the ltx macro only

mandatoryID

If set, elements that create auxiliary files must have an ID (BOOLEAN)

mark1stStyle

If set, use the style to markup the mark1st macro (STRING)

mathPrelude

Like inlatexPrelude but used for the math macro only

noExplicitNumbering

Ignore the explicit numbering in lists (BOOLEAN)

particleStyle

If set to ‘span’, the markup of styles changes. For LaTeX output, this make deplate use proper commands. You can set this for single particles too. (STRING)

pdfOutput

Automatically set when using pdf output (the --pdf command line switch) (BOOLEAN)

pfilter

Include only particles in the output that are tagged with one of these tags. any matched untagged particles. (COMMA-SEPARATED LIST)

prefixID

Prefix autogenerated names for auxiliary files with this string; if not defined, use the current document’s base name (STRING)

ps2imgRes

The resolution used for converting postscript files to bitmaps, e.g., by ps2ppm (NUMBER, default: 120)

refButton

String to be used to represent the wiki references (STRING)

rPrelude

Like inlatexPrelude but used for Img regions of type R

rScanTable

If non-nil, guess column breaks in R tables (BOOLEAN)

stdoutSeparator

A string printed after each output unit when using multi-file output and when redirecting the output to STDOUT (STRING)

styledTags

If set, tags will automatically style an element with style “TAG#{tagname}” (BOOLEAN)

suffix

The suffix to be used when guessing target names referenced by wiki names (STRING)

• <+TBD+>This will be subject of change

tableNumbering

How tables should be numbered (STRING)

flat, document

One counter for all figures

none

No numbering

section (DEFAULT)

Per section

tableStyle

The default style for tables (STRING)

tabwidth

The tab width used when expanding whitespace (NUMBER, default: 4)

tag

Tag all elements with these tags (COMMA-SEPARATED LIST)

template

The default template for the output (STRING)

template_version

Which template engine to use (NUMBER, default: 2)

useParentSuffix

When referring to other files, use the source file’s suffix as fallback strategy (BOOL, default; false)

verbatimMargin

Wrap verbatim regions at this width (NUMBER)

wrapMargin

Wrap margin; set to 0 to prevent text wrap (NUMBER, default: 72)

15.1.3 Output Format

15.1.3.1 HTML

baseUrl

The document’s base url (STRING)

baseUrlStripDir

Number of directories to remove when adding a file name to baseUrl (NUMBER)

bodyOptions

The arguments passed to the body tag (STRING)

css

The document’s CSS file(s) (COMMA-SEPARATED LIST)

• The output media can be defined in the form: CSS|MEDIA

cssExtra

Some extra text to be inserted at css position (STRING or ARRAY OF STRINGS)

cssInclude

Include the contents of the CSS file in the HTML output (BOOLEAN)

docNavbar

If true, display a navigation bar (BOOLEAN)

explorerHack

Code to deal with browser-specific stuff; inserted at head position (STRING or ARRAY OF STRINGS)

headExtra

Other HTML code to be inserted at head position (STRING or ARRAY OF STRINGS)

homeButton

The “home” button in the navigation bar (STRING, default: [-])

htmlAuxUrl, htmlCssUrl, htmlImgUrl

Format string that defines the URLs for images, CSS etc. (STRING)

metaDataExtra

Other HTML code to be inserted at head position (STRING or ARRAY OF STRINGS)

newsFeed

An array of strings defining news feeds for the current site. (STRING or ARRAY OF STRINGS)

• Entry format (please enclose the arguments in quotations marks):
  • rss="URL" title="Title"
  • atom="URL" title="Title"
  • href="URL" title="Title" (defaults to rss)
  • type=rss href="URL" title="Title"
  • type=atom href="URL" title="Title"

nextButton

The “next” button in the navigation bar (STRING, default: >>)

nextKey

The keycode for jumping to the next page (NUMBER, default: 16)

noBindKeys

If true, don’t bind keys for jumping to the previous or next page (BOOLEAN, default: false)

noGenerator

If true, don’t add a generator tag (BOOLEAN, default: false)

noNavMenu

If true, don’t add a menu to the navigation bar (BOOLEAN, default: false)

noSwallow

If true, don’t swallow paragraphs in html-slides output format (BOOLEAN, default: false)

noTabBarButtons

If true, don’t add buttons to the navigation bar (BOOLEAN, default: false)

pageIcon

The page icon tag (STRING)

prevButton

The “previous” button in the navigation bar (STRING, default: <<)

prevKey

The keycode for jumping to the previous page (NUMBER, default: 8)

shortcutIcon

The shortcut icon tag (STRING)

stepwiseDisplay

Whether to display a page step by step (BOOLEAN, default: false)

stepwiseBegin

Number of initially visible elements (INTEGER, default: 1)

stepwiseContinous

Automatically move to the next page if all elements are displayed. If the value is confirm the user will be queried before moving to the next page. (MIXED, default: false)

stepwiseKey

Key code for revealing the next element (COMMA-SEPARATED LIST; default: 34 = ‘PageDn’)

styleExtra

Some extra CSS information that will be wrapped in a style tag (STRING or ARRAY OF STRINGS)

subToC

Print a table of contents for the current section after top level headings (BOOLEAN, default: false)

tabBar

Items in the navigation bar (ARRAY OF STRINGS, default: [“[auto]”])

tabBarButtons

If true, don’t add buttons to the navigation bar (BOOLEAN, default: true)

• <+TBD+>Conflict with noTabBarButtons?

tabEqualWidths

If true, tabs will have equal width (BOOLEAN, default: false)

tabBarHomeName

The display name of the front page in the navigation bar (STRING, default: <+TBD+>)

tabBarSep

The separater between display names and URLs in manual defintions of the navigation bar (STRING, default: |)

tableWidth

The default table width

useDublinCore

If true, use Dublin core tags instead of the standard meta tags (BOOLEAN, default: false)

15.1.3.2 LaTeX

bookClass

Classes that use a \chapter{} command (COMMA-SEPARATED LIST or BOOLEAN)

classOptions

Options passed on to the document class (COMMA-SEPARATED LIST)

typeareaDIV, DIV (koma)

If set, use KOMA script’s typearea package; use this variable to define the proportion of the printed area on a page; see the KOMA script manual for details (NUMBER)

typeareaDIV_, DIV_ (koma)

Same as the above but the parameter is set as a document class option.

floatHere

If true, add a h flag to floats. If H, use the float package and add the H flag. (BOOLEAN or STRING, default: false)

linespread

If set, define the linespread parameter (NUMBER)

noteSize

The font size for margin notes (NUMBER, default: footnotesize)

texLists

If set to wide, the generated source will contain more linebreaks. Otherwise the lines will be more condensed.

useBooktabs

If true, use the booktabs package (BOOLEAN, default: false)

15.1.3.3 LaTeX

sweaveOpts

Document sweave options (STRING)

15.1.3.4 Docbook

copyrightYear

The year field in the copyright section (STRING)

dbkEntities

Entities to be added to the doctype tag (ARRAY OF STRINGS)

dbkVersion

The docbook version to use (STRING, default: 4.2)

manvol

The manual volume to use for dbk-ref output (NUMBER, default: 1)

refentry

The reference category used by for dbk-ref output (STRING)

sgml

If true, try to be SGML compliant; useful when using tools like openjade (BOOLEAN, default: false)

tableFrame

The frame parameter for tables (STRING, default: topbot)

15.1.3.5 Plain Text

asciiArt

Use jave to convert images to ascii representations; possible values: currently only jave (STRING, default: jave)

imgAlt

Fallback display name for images (STRING)

15.1.4 Module

15.1.4.1 Anyword

anyword_catalog

A catalog file containing automatically linked words (STRING)

anyword_list

A comma-separated list of automatically linked words (STRING)

anyword_pattern

A glob pattern for file names in the current directory the base names of which will be added to the list of automatically linked words (STRING)

anyword_suffix

The suffix to use when scanning the directory using anyword_pattern (STRING)

15.1.4.2 CJK

cjk_encoding

The default encoding (STRING, default: GB)

cjk_family

The default font family (STRING, default: gbsn)

noSmartBlanks

If true, guess whether a whitespace should go into the output (BOOLEAN, default: false)

15.1.4.3 entities

entities

List of entities names (COMMA-SEPARATED LIST, default: general)

15.1.4.4 html-headings-navbar

headingsNavbarMaxLevel

Add heading up to this level to the navigation bar (NUMBER)

15.1.4.5 html-sidebar

Deprecated module.

mouseThresholdIn

(NUMBER)

mouseThresholdOut

(NUMBER)

navGif

(STRING)

15.1.4.6 latex-verbatim-small

verbSize

Font size for verbatim regions (NUMBER, default: footnotesize)

15.1.4.7 Mark External URLs

mailtoIcon

The file name of the e-mail icon (STRING, default: mailto.png)

urlIcon

The file name of the external URL icon (STRING, default: url.png)

markerInFrontOfURL

Put the icon in front of the URL (BOOLEAN, default: false)

15.1.4.8 navbar-png

buttonsColour

The subtype of the button images

buttonsFileFormat

The image suffix (STRING, default: png)

buttonsHighlight

Use a rollover effect (BOOLEAN, default: false)

15.1.4.9 Obfuscate E-Mail

noObfuscatedNoscript

If true, put only the name into the noscript tag (BOOLEAN, default: false)

obfuscatedNoscriptAt

How to display the @ sign in the noscript region (STRING, default: AT )

obfuscatedNoscriptDot

How to display periods in the noscript region (STRING, default: DOT )

15.1.4.10 pstoedit

pstoeditArgs

Additional command line arguments (STRING)

15.1.4.11 Smileys

smileySfx

The suffix for smiley image files (STRING, default: png)

15.1.4.12 s5 theme

s5theme

The theme (default: “default)

s5footer

Text to be displayed in the footer

15.1.4.13 validate-html

noCssValid

If true, don’t add a button for CSS validation (BOOLEAN, default: false)

noHtmlValid

If true, don’t add a button for HTML validation (BOOLEAN, default: false)

15.1.4.14 XMLRPC

xmlrpcAllow

A comma-separated list of valid IP addresses of regular expressions matching valid addresses

xmlrpcPath

The path for accessing this xmlrpc server (STRING, default: /deplate)

xmlrpcPort

The xmlrpc server port (NUMBER, default: 2000)

xmlrpcReuseInterpreter

If non-nil, reuse the converter as if the requests were part of one big document (BOOLEAN, default: nil)

15.1.5 Legacy

legacyDefine1

Make #Define type of regions behave as in version up to 0.8 (alternatively, you can pass a noTemplate! argument to the region)

legacyFor1 :: Make #For behave as in version up to 0.8 (alternatively, you can pass a noTemplate! argument to the region)

15.2 Strings, booleans, arrays, and hashes

A variable can be either a string, a boolean, an array, or a hash. The type is defined by the way how it is defined.

Using booleans actually makes only sense in conjunction with if clauses as, in other situations, the value will be represented as the strings “true”/“false”.

String:

#VAR: var=value

Boolean:

#VAR: var!
#VAR: noVar!
#VAR: var=true
#VAR: var=false

Array:

#Var: id=var <<---
Value 1
Value 2
---

#VAR: var[]=value1
#VAR: var[]=value2

Hash:

#VAR: var[field1]=value1
#VAR: var[field2]=value2

The values can be retrieved using the var or val macro.

#VAR: stringVar=Foo

#VAR: boolVar1!
#VAR: noBoolVar2!
#VAR: boolVar3=true
#VAR: boolVar4=false
#VAR: isNoBoolVar1=\true
#VAR: isNoBoolVar2=\false

#Var id=arrayVar1 <<---
Foo
Bar
---

#VAR: arrayVar2[]=foo
#VAR: arrayVar2[]=bar

#VAR: hashVar[field1]=Foo
#VAR: hashVar[field2]=Bar

| stringVar =       | {val: stringVar}                 | {stringVar!} |
| boolVar1 =        | {val: boolVar1}                  | {boolVar1!} |
| boolVar2 =        | {val: boolVar2}                  | {boolVar2!} |
| boolVar3 =        | {val: boolVar3}                  | {boolVar3!} |
| boolVar4 =        | {val: boolVar4}                  | {boolVar4!} |
| isNoBoolVar1 =    | {val: isNoBoolVar1}              | {isNoBoolVar1!} (this is a string) |
| isNoBoolVar2 =    | {val: isNoBoolVar2}              | {isNoBoolVar2!} (this is a string) |
| arrayVar1 =       | {val: arrayVar1}                 | {arrayVar1!} |
| arrayVar2 =       | {val join=", ": arrayVar2}       | {arrayVar2!} |
| hashVar =         | {val join=", " values!: hashVar} | {hashVar!} |
| arrayVar1[0] =    | {val: arrayVar1[0]}              | {arrayVar1[0]!} |
| arrayVar2[1] =    | {val: arrayVar2[1]}              | {arrayVar2[1]!} |
| hashVar[field1] = | {val: hashVar[field1]}           | {hashVar[field1]!} |

Output:

15.3 Template “services”

Some option names have a special meaning in that the content is dynamically generated. Most of them are specific to some output format.

“Services” are meant to generate small, atomic data. Calling a “service” can be distinguished from accessing a variable by adding braces at the end of the service name – which makes it look like a function call in many programming language, which could lead to the question, why I didn’t call it template functions but … heck.

“Services” are provided by the formatter. I.e. they are some kind of formatter specific commands that can be used in templates.

You can use camel case names and underscores according to your liking. someService and some_service do the same thing.

Syntax:

serviceName()
serviceName(KEY1=VALUE KEY2! ...)

Standard services:

• html

  navigation_bar

  Returns a simple navigation bar with a menu and formard/backward buttons (see 9.5.3).

• html-slides

  tabBarLeft, tabBarRight, tabBarTop, tabBarBottom

  returns a tab bar with the table of contents

  progressPercent

  insert the progress as a numeric value

  progressBar, progressBarHorizontal, progressBarVertical

  returns a simple progress bar

These services are most useful for designing templates. The following example contains the template for the HTML online documentation.

15.4 Element properties

Using the #PROP command, you can attach some metainformation to the previous element.

* Heading
#PROP: id=myHeading

• when collapsing elements (e.g. compiling list items to one list), later options overwrite previous ones with the same name

For commands and regions, these options are part of the definition:

#COMMAND optionA=ValueA optionB=ValueB: foo

#Region optionA=ValueA optionB=ValueB <<--
--

So why is there an #PROP command, anyway? It’s there to add more flexibility to elements that are defined in wiki-like markup.

For macros and particles (inline elements), the situation similar. The following two text lines are equivalent:

15.4.1 Global properties

Global properties can be defined in a global hash variable.

The following will tag the heading “Foo” as “heading” and the text in foo.txt with “secondLevel”.

#VAR: $ElementHeading[tag]=heading
#VAR: $INC[tag]=secondLevel

* Foo
#INC: foo.txt

15.5 Tags and filters

The global variable efilter defines which elements to include in the output. Untagged elements use an implicit any tag.

In the following example, we include text stored in a variable in order not to mess up (by filtering elements) the formatting of the main document.

#Var id=tagsExampleInput <<---
* Foo
#PROP: tag=heading

Bar says barly "Bar".
#PROP: tag=bar

Boo says booly "Boo".
#PROP: tag=boo

Foo says fooly "Foo".
#PROP: tag=foo

Something else.
---

#INC $levelshift=2 $efilter=heading,foo,any var=tagsExampleInput

Output:

15.6 Special arguments

The following arguments usually have special meanings. You shouldn’t use these names for macro arguments and the like.

id=NAME

The element’s ID

style=STYLE1,STYLE2,...

The element’s style

swallow!

Don’t print

add! or add=SEPARATOR

the following options will be appended to already existing options of this name using SEPARATOR or a blank (add!)

• the following example sets the element option “test” to “1,2”
• Example (which is equivalent to the #PUSH command):
  • #VAR add=,: test=1
  • #VAR add=,: test=2

type=[body|preMatter|postMatter]

The document section where the element will be put

slot=N

The slot where the element will be put

• If N is negative, the text will be put at the slot’s first position
• See also 16.1.

indentation=[auto|none]

If an element is embedded in a list, you can change the way it is indented in the output.

auto

Let the formatter decide

none

Print left aligned

The fmt and the if options are special in that they are interpreted by deplate and prevent an element from being printed if they are not true:

fmt=FORMATTER

Print the element/particle only if the current output formatter’s name is FORMATTER

• Variants: fmt=~FORMATTER, nofmt=UNMATCHED FORMATTER, nofmt=~UNMATCHED FORMATTER
• Example:
  • #VAR fmt=html:  class=mycss
  • #VAR fmt=latex: class=report

if=VAR

Print the element/particle only if the test evaluates to true

• Variants: if=noVAR, if=(VAR==VALUE), if=(VAR!=VALUE), if=(VAR=~VALUE), if=(VAR!=~VALUE)
• the if clause should be put in parentheses or double quotes in order to avoid parse errors
• the element/particle will be inserted only if the document variable VAR is set or matches/doesn’t match VALUE
• if the docoption begins with “no” and the next letter is in upper case, the docoption’s name will be converted to lower case and tested against its non-presence; see 12.5 for an example
• Example:
  • #TITLE if=(outcome==good): Hurray!

15.7 Clips

Clips are formatted text that were saved for later use. In opposition to variables, which are formatted after insertion, clips are formatted independently from where they are used.

Some command generate clips automatically. These auto-created clips are:

author

The document’s author

authornote

A note about the author

title

The document’s title

date

The document’s creation date