GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  DEPLATE (1)

NAME

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

CONTENTS

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:
o ~/.deplate/
o config.rb (the general user configuration file, which is loaded last)
o deplate.ini (an alternative way to configure deplate)
o after/ (files that are loaded right after the corresponding formatter or module)
o fmt/
o input/
o mod/
o css/ (user defined css files)
o fmt/ (user defined formatters)
o input/ (user defined input definitions)
o lib/ (user defined deplate snippets)
o FORMATTER/ (output-format specific deplate snippets)
o mod/ (user defined modules)
o 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
o restrict the markers for unordered lists to "#"
o 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)
o 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 ...)
o 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
o 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:
o these variables (array of arrays of strings) can be redefined in Deplate::Core.user_setup to put some formatted output on every page/file
o @@pre_matter_template
o @@body_template
o @@post_matter_template
o this variable (array of strings) can contain some deplate markup that will be prepended to every file read
o @@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 Strae 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
Search for    or go to Top of page |  Section 1 |  Main Index


DEPLATE (1) 06. Feb 2009

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.