DEPLATE(1)DEPLATE(1)NAMEdeplate - 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
06. Feb 2009 DEPLATE(1)
