4 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, 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:
CVS, 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 8.

-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, see 5.1.

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

If you are a ruby programmer, you can also use deplate as a library for formatting strings. You could use the convenience classes Deplate::Converter or DeplateString for this.

require 'deplate/converter'

t = <<EOF
* Introduction

''deplate'' is a tool for converting wiki-like markup to latex, html, or 
"html-slides".
EOF

to_html = Deplate::Converter.new
puts to_html.convert_string(t)

to_latex = Deplate::Converter.new("latex")
puts to_latex.convert_string(t)

or:

require 'deplate/deplate-string'

t = <<EOF
* Introduction

''deplate'' is a tool for converting wiki-like markup to latex, html, or 
"html-slides".
EOF

puts DeplateString.new(t).to_html

The DeplateString is probably easier to use from within other programs like e.g. Nukumi2 (see 9.9.2).

4.1 Editor support

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

4.1.2 VIM

deplate is the accompanying converter for the Vim viki plugin, which supports all of deplate‘s default markup.