5 Configuration

Configuration requires some knowledge of the ruby language. If you don’t already know ruby, ruby is a well designed, fully object-oriented interpreted language in the spirit of Smalltalk (but with a rather modern syntax) plus some features from Perl and Lisp/Scheme (e.g. continuations).

The configuration files are regular ruby files and are loaded after requiring all the libraries necessary. Theses files reside in the directory “$HOME/.deplate/” or “$USERPROFILE/deplate.rc/”. If these directories are not found, the files are searched in $WINDIR/deplate.rc/ or /etc/deplate.rc/. Some files are also looked for in the “datadir” (usually something like /usr/share/deplate/).

This directory may also contain custom modules or css files etc. On Win 2000/XP etc., $USERPROFILE is usually set to “C:\Documents and Settings\USERNAME\”. See also 17 for how to add new elements, particles, macros etc.

The user configuration directory should look like this:

• ~/.deplate/
  • config.rb (the general user configuration file, which is loaded last)
  • deplate.ini (an alternative way to configure deplate)
  • after/ (files that are loaded right after the corresponding formatter or module)
    • fmt/
    • input/
    • mod/
  • css/ (user defined css files)
  • fmt/ (user defined formatters)
  • input/ (user defined input definitions)
  • lib/ (user defined deplate snippets)
    • FORMATTER/ (output-format specific deplate snippets)
  • mod/ (user defined modules)
  • templates/ (user defined templates)

If the user requests loading “MODULE”, deplate searches for “~/.deplate/mod/MODULE.rb” first, then in ruby site-library. If it was found and loaded, the file “~/.deplate/after/mod/MODULE.rb” will be sourced, too – if available.

deplate calls the class method Deplate::Core.user_setup after processing the command line argumend. It calls the instance method Deplate#user_initialize after the new instance of the deplate converter was created and initialized, right before actually performing the conversion.

In general, configuration is done by patching ruby classes. In the following example, we

• restrict the markers for unordered lists to “#”
• define Koma-Script’s article class as the default latex class

class Deplate::List::Itemize
    @rx = /^(([ \t]+)(#)[ \t]+)(.+)$/
end

class Deplate::Formatter::LaTeX
    @@latexDocClass = "scrartcl"
end

Here is another example from my personal “after/fmt/latex.rb” file.

class Deplate::Formatter::LaTeX
    def hook_pre_prepare_my_configuration
        suppl   = @deplate.variables["suppl"]                    #1
        suppl &&= "[" + suppl + "]"
        output_at(:pre, :user_packages, "\\usepackage#{suppl}{suppl}")

        t = @deplate.get_clip("title")                           #2
        output_at(:pre, :body_title, "\\tmltitle{#{t.elt}}") if t
        a = @deplate.get_clip("author")
        output_at(:pre, :body_title, "\\tmlauthor{#{a.elt}}") if a
        d = @deplate.get_clip("date")
        output_at(:pre, :body_title, "\\tmldate{#{d.elt}}") if d
    end
end

1. Add a usepackage statement to the preamble – with optional arguments from the “suppl” variable.
2. extracts information about the document’s title and author and adds some user-defined commands to the document preamble – but below any usepackage statements (see 15.6).

5.1 User configuration of the standard setup

deplate calls the methods Deplate::Core.user_setup(options) and Deplate::Core#user_initialize if they are defined in order to provide a possibility to hook into the standard setup procedure.

Deplate::Core.user_setup is called when starting deplate from the command line and before a instance of Deplate::Core was created. This method should be used to set values in the options structure or to permanently require one of deplate‘s modules.

Deplate::Core#user_initialize is called after an instance of Deplate::Core was created and should be used to set variables specific to this instance.

5.2 Configuration of wiki names

Usually, any word in CamelCase (a.k.a. wiki name) is turned into a hyperlink. By default only the letters A-Z and a-z are allowed here in order to minimize possible conflicts between different encodings and different versions of ruby on different systems with different locales in effect. If this doesn’t fit your needs, maybe because you happen to write in a language other than English, which is possible and maybe even likely, you might want to change this. Add something like this with the new character sets to your config.rb file:

class Deplate::HyperLink
    @@uc = 'A-ZÄÖÜ'
    @@lc = 'a-zäöüßáàéèíìóòçñ'
end

# the following re-compiles the regexps for wiki names
Deplate::HyperLink.setup

If you really don’t like simple wiki names and want to disable the all together, you can put something like this into your config.rb:

5.3 Configuration via deplate.ini

If you don’t want to configure deplate using ruby, you can put some settings into the deplate.ini file, which usually resides in ~/.depate and/or #{PWD}/deplate.rc. Themes can also have their own ini files.

This file contains a sequence of commands. Each command must fit in one line. The following commands are allowed:

allow FLAGS

Allow deplate to do certain things(see 4)

• If you use deplate only for your own files, you might want to run deplate in “unsafe” mode by adding allow all to your deplate.ini file.

--OPTION

Additional command line option

mod NAME

Load the module NAME

fmt NAME

Set the standard formatter

clip NAME=VALUE

Set the clip NAME (e.g., “author”) to VALUE

wiki NAME.SUFFIX=BASEURL

Define an interwiki (the .SUFFIX part is optional)

wikichars UPPERCHARS LOWERCHARS

Define which characters are allowed in wiki names

app NAME=COMMANDLINE

Define an external app (e.g., latex, dvips, R, dot, neato, pstoedit, identify, gs …)

• If you get a Exec format error error, this is probably caused by a missing executable suffix. To avoid this error, redefine the app and add a .exe or similar to the name.

$ENV=VALUE

Set an environment variable

VAR=VALUE

Set variable VAR to VALUE

• Alternatively, variables can contain multi-line values using the usual heredoc pattern (<<MARKER\nTEXT...\nMARKER\n) as long as the smaller characters (“<<”) appear right after the equals sign. Internally, a multi-line value is processed as array.

Although this may not always work as expected, you can also set some options (as defined in  5.4) by prepending the name with a colon (“:”) or by using the option keyword:

option NAME~

Set option NAME to false

option NAME!

Set option NAME to true

option NAME?=true|false|yes|no|on|off

Set option NAME to a boolean value

option NAME%=INTEGER

Set option NAME to a numeric value

option NAME=VALUE

Set option NAME to VALUE as string

Lines beginning with one of *%#; are considered comments.

; Disable simple wiki names
--no-simple-names

; Load some standard modules
mod de
mod mark-external-urls
mod colored-log

; Applications
app dot=/somewhere/not/in/the/standard/path/dot
app latex=latex_wrapper.sh

; Clips
clip author=Thomas Link

; Options
; Enable full LaTeX, support for ruby code & external applications
allow t x X

; By default, use only a subset of deplate's standard markup
option input_def=deplate-restricted

; Create latex output by default
option fmt=latex

; Wikis
wikichars A-ZÄÖÜ a-zäöüßáàéèíìóòçñ
wiki DEPLATE.html=http://deplate.sf.net/

; Variables
;; HTML
css=deplate.css

topBar=<<----
[auto]
MyOtherHomepage | http://www.homepage.org
----

;; Save auxiliary files in a subdirectory (BASENAME_files)
auxiliaryDirSuffix=_files

5.4 Options

Most command line options correspond to fields in the (open) structure Deplate#options. You could thus make your choices permanent by adding something like this to your config.rb configuration file:

class Deplate::Core
    def self.user_setup(options)
        options.field_name = 'some value'           # ok
        options.allow_exec = true                   # example
    end

    def user_initialize
        @variables['NAME'] = 'VALUE'                # ok
        @options.other_field_name = 'some value'    # deprecated
    end
end

The variable options is meant to influence the whole setup and should contain variables that cannot be set directly by a document. variables are meant to specific to the current conversion process. While options should be set in Deplate#user_setup, variables should be defined in Deplate#user_initialize.

Here is a mostly complete table of command line options and corresponding option fields:

The command-line option “-x” or “--allow-ruby [RUBY SAFE]” currently sets the class variable @@allow_ruby and the global variable $SAFE (if an integer is provided). --verbose sets Deplate’s class variable @@verbose.

5.5 Templates

deplate supports two ways of page templates:

1. Template variables
2. Template files

5.5.1 Template variables (obsolete)

You can define a template in ruby by setting the following Deplate class variables:

• these variables (array of arrays of strings) can be redefined in Deplate::Core.user_setup to put some formatted output on every page/file
  • @@pre_matter_template
  • @@body_template
  • @@post_matter_template
• this variable (array of strings) can contain some deplate markup that will be prepended to every file read
  • @@deplate_template

Typical use would be (in your config.rb file)

class Deplate
    def self.user_setup(options)
        if options.fmt =~ /^html/
            @@post_matter_template[10] = ['<br>\n(c) 2004, Me']
        end
        @@deplate_template << '#AU: My Name'
    end
end

5.5.2 Template files

Via the -t or --template command-line option or by setting the template document variable (see 15.1), you can define simple text templates that will be filled in with content from your deplate file.

Since version 0.7, deplate uses a specialized formatter for handling templates. Before 0.7, this was done by search & replace. If you have pre 0.7 templates which don’t work any more, you can switch back to the old template mechanism by setting the document option template_version to 1.

In templates, only a small number of statements are available:

Commands

GET, ARG, XARG, VAR, OPT, PREMATTER, POSTMATTER, BODY, IF, ELSE, ELSEIF, ENDIF, INC/INCLUDE

Regions

Foreach, Mingle, Ruby, Var

Macros

get, clip, opt, arg, xarg, doc, ruby

The commands PREMATTER, POSTMATTER, BODY as well as the Mingle region are specific to templates.

PREMATTER, POSTMATTER, and BODY can be used to fill in formatted content for an explanation of deplate‘s document structure):

#PREMATTER

The file header, the beginning of the document definition, some text that in multi-file mode should appear in every output file

#BODY

The text body

#POSTMATTER

Some text that in multi-file mode should appear in every output file, the end of document definition

These commands take a list of slots (named or as numbers) as arguments. The slots can be single slots or ranges. They can be positive (add selectively) or negative (add with the exception of certain content). Examples:

#PREMATTER: -doc_def

add the prematter without the document type definition

#PREMATTER: doc_def mod_packages mod_head

add the document type definition, and stuff added by modules

#PREMATTER: head_beg..prematter_end

add everything from the head on downwards

A slot cannot be consumed twice. I.e., if you use several template commands, the latter will not insert the content that was already inserted by the previous command.

The Mingle region can be used to add some text to a specific slot in the original document. Filling in templates takes place after the document was produced. A template actually processed by deplate like normal text but with a different active rule set. Thus, if you define a slot or a type for a region in the template file these definitions refer to the template output which usually is not quite what you want. You can use Mingle to make them refer to the original document. See html-left-tabbar-js.html in the templates subdirectory of the distribution for an example.

Curly braces in templates could cause problems because deplate maybe interpretes them as macros. If deplate mixes up your template, you should prefix these curly braces that cause problems with a backslash.

Backslashes have always to be doubled.

In this example, we use get for the author’s name because the corresponding clip is automatically defined by the standard #AU(THOR) command. For other data we use variables.

Template: tmpl_letter.tex

\\documentclass[12pt,a4paper,english]{letter}
#PREMATTER: -doc_def
\\address{{get: author}\\\\
    {val escapebackslash!: address}}
\\signature{{get: author}}

\\begin{letter}{{val: addresseeName}\\\\
    {val escapebackslash!: addresseeAddress}}
\\opening{Dear {val: addresseeName},}

#BODY

\\closing{Sincerly,}
\\vfill{}
\\encl{{val: enclosure}}
\\end{letter}
#POSTMATTER

Input file: example-letter.txt

#AU: John Smith
#DATE: today
#VAR id=address: Cool Place 1{nl inline!}Hiptown 10000
#VAR id=enclosure: Important Document
#VAR: addresseeName=Max Mustermann
#VAR: addresseeAddress=Tolle Straße 2{nl}Neustadt 20000

I would like to say thanks for your last letter which I read with much joy. I
hope to be hearing from you soon.

Command line:

deplate -t tmpl_letter.tex -f latex example-letter.txt
pdflatex example-letter.tex

Result: example-letter.pdf