DEPLATE(1)

NAME
deplate - Deplate 0.8.5 -- convert wiki-like markup to latex, docbook, html, or "html-slides"

USAGE

The command-line options:

Usage: deplate.rb [OPTIONS] FILE [OTHER FILES ...]
deplate is a free software with ABSOLUTELY NO WARRANTY under
the terms of the GNU General Public License version 2.
General Options:
    -a, --[no-]ask                   On certain actions,
    query user before overwriting files
    -A, --allow ALLOW                Allow certain things:
    l, r, t, w, W, x, X, $
    -c, --config FILE                Alternative user cfg
    file
        --[no-]clean                 Clean up temporary files
        --color                      Colored output
        --css NAME                   Copy NAME.css to the
        destination directory, if inexistent
        --copy-css NAME              Copy NAME.css to the
        destination directory
    -d, --dir DIR                    Output directory
    -D, --define NAME=VALUE          Define a document option
    -e, --[no-]each                  Handle each file
    separately
        --[no-]force                 Force output
    -f, --format FORMAT              Output format (default:
    html)
        --[no-]included              Output body only
    -i, --input NAME                 Input definition
        --list FILE                  A file that contains a
        list of input files
        --log FILE                   A file (or - for
        stdout) where to put the log
        --[no-]loop                  Read from stdin forever
        and ever
        --metadata [NAME]            Save metadata in this
        format (default: yaml)
    -m, --module MODULE              Load a module
    -o, --out FILE                   Output to file or
    stdout ('-')
    -p, --pattern GLOBPATTERN        File name pattern
    -P, --exclude GLOBPATTERN        Excluded file name
    pattern
    -r, --[no-]recurse               Recurse into directories
        --reset-filecache            Reset the file database
    -R, --[no-]Recurse               Recurse and rebuild
    hierarchy
    -s, --skeleton NAME              Make skeleton available
        --[no-]simple-names          Disable simple wiki
        names
        --split-level LEVEL          Heading level for
        splitting
        --suffix SUFFIX              Suffix for output files
    -t, --template NAME              Template to use
        --theme THEME                Theme to use
        --[no-]vanilla               Ignore user
        configuration
    -x, --allow-ruby [RUBY SAFE]     Allow the execution of
    ruby code
    -X, --[no-]allow-exec            Allow the execution of
    helper applications
        --[no-]external
LaTeX Formatter:
        --[no-]pdf                   Prepare for use with
        pdf(la)tex
Available input defintions:
deplate, deplate-headings, deplate-restricted, play, rdoc,
template
Available formatters:
dbk-article, dbk-article-4.1.2, dbk-book, dbk-ref,
dbk-slides, dbk-snippet, html, html-snippet, htmlsite,
htmlslides, htmlwebsite, latex, latex-dramatist,
latex-snippet, null, php, phpsite, plain, sweave, template,
xhtml10t, xhtml11m
Available metadata formats:
marshal, xml, yaml
Available modules:
anyword, babelfish, code-coderay, code-gvim, code-gvim71,
code-highlight, colored-log, encode, endnotes,
entities-decode, entities-encode, guesslanguage,
html-asciimath, html-deplate-button, html-headings-navbar,
html-highstep, html-jsmath, html-mathml,
html-obfuscate-email, html-sidebar, htmlslides-navbar-fh,
iconv, imgurl, inlatex-compound, koma, lang-de, lang-en,
lang-ru, lang-ru-koi8-r, lang-zh_CN, lang-zh_CN-autospace,
latex-emph-table-head, latex-styles, latex-verbatim-small,
linkmap, makefile, mark-external-urls, markup-1,
markup-1-warn, navbar-png, noindent, numpara, particle-math,
php-extra, pstoedit, recode, smart-dash, smiley, soffice,
symbols-latin1, symbols-od-utf-8, symbols-plain,
symbols-sgml, symbols-utf-8, symbols-xml, syntax-region-alt,
utf8, validate-html, xmlrpc
Available themes:
navbar-right.html, presentation.html, s5.xhtml
Available css files:
article, deplate, doc, heading-navbar, highlight, highstep,
htmldoc, layout-deplate, layout-deplate-print, play,
presentation, presentation_highstep, presentation_website,
sans-serif, screenplay, serif, serif-e, serif-rel, slides,
styles, tabbar, tabbar-left, tabbar-right, tabbar-right-ie,
tabbar-top, text-sans-serif, text-serif, websitary, website
Available templates:
html-doc.html, html-left-tabbar-js.html,
html-left-tabbar.html, html-tabbar-right-pcomments.php,
html-tabbar-right-step.html, html-tabbar-right-table.html,
html-tabbar-right.html, html-tabbar-top.html,
html-tabbar.html
Other Options:
        --debug [LEVEL]              Show debug messages
        --[no-]profile               Profile execution
        --[no-]quiet                 Be quiet
    -v, --[no-]verbose               Run verbosely
    -h, --help                       Show this message
        --list-modules [REGEXP]      List modules matching a
        pattern
        --list-css [REGEXP]          List css files matching
        a pattern
        --version                    Show version
        --microversion               Show version

Typical uses of deplate are:

deplate -D auxiliaryDirSuffix=_files text.txt
    Convert the file to html; put auxiliary files that are created during the conversion process into a subdirectory called "text_files"

deplate -d DESTDIR -f htmlslides text*.txt
    Convert a bunch of files to "html slides"; put the output into "DESTDIR"

deplate -f latex --pdf -D suffix=txt text*.txt
    Convert a bunch of files to a single LaTeX file and prepare for pdflatex; assume that the wiki files have a "txt" extension; wiki names referring to included files are transformed to internal references

deplate -R -p '\*.txt' -D suffix=txt -o ../Wiki.tex WikiIndex.txt *
    Convert all files in the current directory and below to a single LaTeX file; include only files with "txt" as suffix; put WikiIndex.txt first

deplate -R -e -d ../Wiki_html *
    Convert all files in the current directory and its subdirectories to html; save the output in directory Wiki_html; rebuild the directory structure of the input files

deplate - < INPUT > OUTPUT
    Work as a filter by converting the input from stdin; this doesn't actually work like a pipe though because all the input has to be read in order to generate the output

deplate -x -X file.txt
    Convert a file and allow the evaluation of embedded ruby code and the execution of external applications, e.g., latex. These command switches are necessary for some language elements to work.

Notes:

-D VAR, -D VAR=VALUE
    You can define document variables via the command line; if no value is provided the variable is set to "1". The option parser library, which deplate uses, doesn't deal well with spaces in command line arguments. This is why spaces have to be replaced with tildes; a tilde and backslashes have to be preceded with backslashes. Example: -D text=bla~bla\~bla sets the document variable text to "bla bla~bla". As a shell usually interpretes backslashes too, you would usually have to type -D text=bla~bla\\~bla.

-e  Process each file separately

-m, --module MODULE
    Load an add-on/module (after loading the core and the formatter); modules reside in the deplate library directory or in the user configuration directory ("~/.deplate/mod/"); type deplate --help to see a list of available modules.

    After loading the module, deplate searches for the file "~/.deplate/after/mod/NAME.rb" which will be loaded if found.

    German, Chinese, and Russian localizations are provided as modules.

-p PATTERN, -P PATTERN
    Backslashes in the pattern must come in doubles; backslashes can be used to prevent the shell from expanding the pattern; e.g., in case you're using bash, you would usually type something like -p "\\*.txt"

--theme THEME
    See ??.

-x, --allow-ruby [RUBY SAFE]
    Ruby's SAFE variable has 5 levels (0=no checks/default .. 4=sandbox; at present, this also sets the SAFE variable for deplate itself, which doesn't work with SAFE set to 4)

-X, --[no-]allow-exec, --[no-]external
    Allow the execution of external applications, e.g., LaTeX. You won't be able to translate inline LaTeX unless you call deplate with this command line option. In order to make this permanent.

-A, --allow FLAGS
    Flags is a list of comma separated letters which may contain:

    all Unsafe mode; allow everything

    l   Allow the #LANG command to automatically load a module of the language's name (this would make it possible for a malicious user to load any module as deplate cannot distinguish localization modules from other modules)

    r   Check files in $PWD/deplate.rc in some cases (e.g. check for a local config.rb); templates, css files, and library snippets are always searched in the deplate.rc directory too; if you want to allow a deplate.ini file in this directory, you have the add allow r to your private deplate.ini file (usually in ~/.deplate/)

    s   Load {theme}/theme.ini if any (this might be necessary for most themes to be fully functional)

    t   Unfiltered (La)TeX

    w   Enable the #Write region (directory local file names only)

    W   Enable the #Write region (allow relative & absolute file names)

    x   Same as -x

    X   Same as -X

    Allow sending methods to objects in the
        arg macro and friends.

    :   Allow referencing options by prepending a name with ":" in some situations (e.g. #IF tests).

    You can remove the permission to do something by prepending a minus to the flag, e.g. by setting --allow -x on the command line after having allowed x in the deplate.ini file.

Some variables change the way deplate works.

autoFileNames
    In multi-file output, the file name is constructed from the top heading unless explicitely defined (id, caption, shortcaption)

auxiliaryDirSuffix
    If defined, auxiliary files are saved in the subdirectory #{basename FILENAME}#{auxiliaryDirSuffix}. E.g., if auxiliaryDirSuffix is "_files" and the current file is "Test", then auxiliary files (images, on-the-fly generated files that are passed to external applications etc.) are saved in "Test_files".

  Editor support

General remark

    As whitespace is significant in the context of lists and the like, you should not insert tab characters in the document but replace tabs with blanks/spaces. Most editors can be tweaked to work this way.

    If you absolutely want to insert tab characters or if you don't know how to keep your editor from inserting tabs, you can set the tabwidth (default: 4) variable to the tab width setting of your editor. deplate will then try to expand tab characters.

VIM

    deplate is the accompanying converter for the [1]Vim viki plugin, which supports all of deplate's default markup.

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\".

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.

  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.

class Deplate::Core
    def self.user_setup(options)
        options.field_name = 'some value'
        require_module(options, 'NAME')
    end
    def user_initialize
        @variables['NAME'] = 'VALUE'
    end
end

  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:

class Deplate::Core
    def self.user_setup(options)
        options.disabled_particles << Deplate::HyperLink::Simple
    end
end

  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 Usage)

    •   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 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 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 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.

Example 2.1: deplate.ini

; 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

  Templates

deplate supports two ways of page templates:

1.  Template variables

2.  Template files

    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

Template files

    Via the -t or --template command-line option or by setting the template document variable, 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.

    Example 2.2: A letter template

    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: [2]example-letter.pdf

REFERENCES

1. Vim viki plugin
    http://www.vim.org/scripts/script.php?script_id=861

2. example-letter.pdf
    example-letter.pdf