deplate 0.7.3

data/lib/ps2ppm.rb

@@ -0,0 +1,239 @@
+#!/usr/bin/env ruby
+# ps2ppm.rb
+# @Author:      Peter Kleiweg
+# @Created:     11-Nov-2004.
+# @Last Change: 30-Jul-2005.
+# @Revision:    0.101
+#
+# Ruby translation of the ps2ppm script that can be found 
+# http://odur.let.rug.nl/~kleiweg/postscript/ps2ppm 
+# here. 
+#
+# Note that this is still very perlish.
+# 
+# The original perl script is by Peter Kleiweg.
+# Kaspar Schiess (eule AT space.ch) converted this script to ruby.
+# 
+# This is a slightly modified and de-perlished version of his converted script.
+#
+
+require 'getopts'
+# require 'pp'
+
+module Ps2ppm
+    @gsname   = "gs"
+    # @gsname   = "gs.bat"
+    @progname = "ps2pmm"
+    @default = 'ppmraw'
+       
+    def syntax
+        puts <<EOS
+
+PostScript to Pixelmap(s) Converter
+(C) P. Kleiweg 1996-1999
+
+Usage: #{@progname} [-1ghot] [-f format] [-m margin] [-O orientation] [-r resolution] file[.[e]ps]
+
+  -1: old PostScript Level 1 method (unsafe?)
+  -f: format (default #{@default}), for listing type: gs -h
+  -g: anti-alias graphics (try it)
+  -h: this help
+  -m: margin (default 0)
+  -O: orientation (overrides %%Orientation comment)
+      valid orientations are: Portrait Landscape Upside-Down Seascape
+  -o: force overwrite
+  -r: resolution (default 72)
+  -t: anti-alias text (recommended)
+
+EOS
+        exit
+    end
+    module_function :syntax
+
+    def run(file, opt={})
+        syntax unless file
+
+        level     = 2
+        format    = @default
+        margin    = 0
+        overwrite = 0
+        orient    = 'Portrait'
+        res       = 72
+        gab       = ''
+        tab       = ''
+        values    = []
+        
+        level     = true                    if opt['1']
+        format    = opt['f']                if opt['f']
+        margin    = Float(opt['m'])         if opt['m']
+        overwrite = true                    if opt['o']
+        res       = Integer(opt['r'])       if opt['r']
+        gab       = '-dGraphicsAlphaBits=4' if opt['g']
+        tab       = '-dTextAlphaBits=4'     if opt['t']
+
+        case format
+        when "jpeg"
+            # values << "-dQFactor=1.0"
+            values << "-dJPEGQ=100"
+        end
+        
+        out_file1 = "#{file}.01.#{format}"
+        
+        # If you have problems with anti-aliasing, try uncommenting this:
+        # if opt['g'] or opt['t']
+        #     values << '-dRedValues=256 -dGreenValues=256 -dBlueValues=256 -dGrayValues=256'
+        # end
+        
+        infile = file
+        file = file.sub( /\.[eE]?[Pp][Ss]$/, '' )
+        unless infile =~ /\.[eE]?[Pp][Ss]$/ 
+            infile += '.ps'
+        end
+        
+        if FileTest.file?(out_file1) && (! overwrite)
+            raise "File exists: #{out_file1}";
+        end
+        
+        found  = false
+        level  = 0
+        x1     = nil
+        y1     = nil
+        x2     = nil
+        y2     = nil
+        found  = nil
+       
+        postscript = nil
+        File.open( infile, 'rb' ) do |io|
+            postscript = io.readlines
+        end
+        postscript.each do |line|
+            if level == 0 and line =~ /^%%BoundingBox:\s*(-?\d+)\s+(-?\d+)\s+(-?\d+)\s+(-?\d+)/
+                x1 = Integer($1)
+                y1 = Integer($2)
+                x2 = Integer($3) 
+                y2 = Integer($4)
+                found = true 
+            elsif level == 0 and line =~ /^%%Orientation:\s*(\S+)/
+                o = $1
+                if o =~ /^portrait$/i 
+                    orient = 'Portrait';
+                elsif o =~ /^landscape$/i
+                    orient = 'Landscape'
+                elsif o =~ /^upside-?down$/i
+                    orient = 'Upside-Down'
+                elsif o =~ /^seascape$/i
+                    orient = 'Seascape'
+                end
+            elsif line =~ /^%%BeginDocument\b/
+                level += 1
+            elsif line =~ /^%%EndDocument\b/
+                level -= 1
+            end
+        end
+        found or raise "BoundingBox not found in #{file}.ps"
+
+        if opt['O']
+            case opt['O']
+            when /^portrait/i
+                orient = 'Portrait'
+            when /^landscape$/i
+                orient = 'Landscape'
+            when /^upside-?down$/i
+                orient = 'Upside-Down'
+            when /^seascape$/i
+                orient = 'Seascape'
+            else 
+                raise 'Illegal orientation'
+            end
+        end
+
+        trans = ''
+
+        if margin != 0
+            trans << "#{margin} dup translate "
+        end
+
+        case orient
+        when 'Portrait'
+            w = x2 - x1
+            h = y2 - y1
+        when 'Landscape'
+            w = y2 - y1
+            h = x2 - x1
+            t = -h
+            trans << "-90 rotate #{t} 0 translate "
+        when 'Upside-Down'
+            w = x2 - x1
+            h = y2 - y1
+            ww = -w
+            hh = -h
+            trans << "180 rotate #{ww} #{hh} translate "
+        when 'Seascape'
+            w = y2 - y1
+            h = x2 - x1
+            t = -w
+            trans << "90 rotate 0 #{t} translate "
+        else
+            raise "Unknown orientation: %s" % orient
+        end
+
+        w = ((2.0 * margin + w) * res / 72.0).to_i
+        h = ((2.0 * margin + h) * res / 72.0).to_i
+
+        x = -x1
+        y = -y1
+        trans << "#{x} #{y} translate"
+
+        puts "#{file}.ps -> #{file}.%02d.#{format}"
+
+        if defined?(Deplate::External.get_app)
+            gsname = Deplate::External.get_app('gs', @gsname)
+        else
+            gsname = @gsname
+        end
+        cmdline = "#{gsname} -dDOINTERPOLATE #{values.join(" ")} #{gab} #{tab} -g#{w}x#{h} -r#{res} -sDEVICE=#{format} -sOutputFile=#{file}.%02d.#{format} -dNOPAUSE -"
+        IO.popen(cmdline, 'w') do |gs|
+
+            if level == 1
+                gs.puts <<LEV1HEAD
+/showpage {
+  showpage
+  #{trans}
+  (.) print flush
+} bind def
+#{trans}
+LEV1HEAD
+            else
+                gs.puts <<LEV2HEAD
+<<
+    /BeginPage {
+        pop
+        #{trans}
+    }
+    /EndPage {
+        dup 0 eq {
+            pop
+            1 add 4 string cvs print ( ) print flush
+            true
+    } {
+            1 eq
+            exch pop
+    } ifelse
+    }
+>> setpagedevice
+LEV2HEAD
+            end
+            gs.puts postscript
+            gs.puts "\nquit\n"
+            return File.exist?(out_file1)
+        end
+    end
+    module_function :run
+end
+
+if __FILE__ == $0
+    file = ARGV.pop
+    getopts('1f:ghm:oO:r:t')
+    Ps2ppm.run(file, $OPT)
+end
+

data/man/man1/deplate.1

@@ -0,0 +1,692 @@
+.\"Generated by db2man.xsl. Don't modify this, modify the source.
+.de Sh \" Subsection
+.br
+.if t .Sp
+.ne 5
+.PP
+\fB\\$1\fR
+.PP
+..
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Ip \" List item
+.br
+.ie \\n(.$>=3 .ne \\$3
+.el .ne 3
+.IP "\\$1" \\$2
+..
+.TH "DEPLATE" 1 "02. Nov 2005" "" ""
+.SH NAME
+deplate \- Deplate - convert wiki-like markup to latex, docbook, html, or �html-slides�
+.SH "USAGE"
+
+.PP
+The command\-line options:
+
+.IP
+
+    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: 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
+            \-\-[no\-]simple\-names          Disable simple wiki names
+            \-\-suffix SUFFIX              Suffix for output files
+        \-t, \-\-template NAME              Template 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, 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\-snippet, php, phpsite, plain, template, xhtml10t
+    
+    
+    Available metadata formats:
+    marshal, xml, yaml
+    
+    
+    Available modules:
+    anyword, babelfish, code\-gvim, code\-highlight, colored\-log, de,
+    en, endnotes, fr, html\-asciimath, html\-deplate\-button, html\-headings\-navbar,
+    html\-obfuscate\-email, html\-sidebar, htmlslides\-navbar\-fh, iconv,
+    imgurl, inlatex\-compound, koma, latex\-emph\-table\-head, latex\-styles,
+    latex\-verbatim\-small, makefile, mark\-external\-urls, markup\-1,
+    markup\-1\-warn, navbar\-png, noindent, numpara, particle\-math,
+    php\-extra, pstoedit, recode, ru_koi8\-r, smiley, soffice, symbols\-latin1,
+    symbols\-od\-utf\-8, symbols\-plain, symbols\-sgml, symbols\-utf\-8,
+    symbols\-xml, syntax\-region\-alt, utf8, validate\-html, xmlrpc,
+    zh\-cn, zh\-cn\-autospace
+    
+    
+    Available css files:
+    article, deplate, heading\-navbar, layout\-deplate, layout\-deplate\-print,
+    sans\-serif, serif, serif\-e, serif\-rel, slides, tabbar, tabbar\-left,
+    tabbar\-right, tabbar\-right\-ie, tabbar\-top, text\-sans\-serif, text\-serif
+    
+    
+    Available templates:
+    CVS, html\-doc\&.html, html\-left\-tabbar\-js\&.html, html\-left\-tabbar\&.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
+            \-\-version                    Show version
+            \-\-microversion               Show version
+    
+.PP
+Typical uses of deplate are:
+
+.TP
+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�
+
+.TP
+deplate \-d DESTDIR \-f htmlslides text*\&.txt
+Convert a bunch of files to �html slides�; put the output into �DESTDIR�
+
+.TP
+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
+
+.TP
+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
+
+.TP
+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
+
+.TP
+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
+
+.TP
+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\&.
+
+.PP
+Notes:
+
+.TP
+\-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\&.
+
+.TP
+\-e
+Process each file separately
+
+.TP
+\-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\&.
+
+.TP
+\-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"
+
+.TP
+\-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)
+
+.TP
+\-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\~[xref to anchor]\&.
+
+.TP
+\-A, \-\-allow FLAGS
+Flags is a list of comma separated letters which may contain:
+
+.RS
+
+.TP
+x
+Same as \-x
+
+.TP
+X
+Same as \-X
+
+.TP
+:
+Allow referencing options by prepending a name with �:� in some situations (e\&.g\&. #IF tests)\&.
+
+.RE
+.IP
+
+.PP
+Some variables change the way deplate works\&.
+
+.TP
+autoFileNames
+In multi\-file output, the file name is constructed from the top heading unless explicitely defined (id, caption, shortcaption)
+
+.TP
+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�\&.
+
+.SS "Editor support"
+
+.PP
+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\&.
+
+.PP
+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\&.
+
+.PP
+deplate is the accompanying converter for the Vim viki plugin: \fIhttp://www.vim.org/scripts/script.php?script_id=861\fR, which supports all of deplate�s default markup\&.
+
+.SH "CONFIGURATION"
+
+.PP
+Configuration requires some knowledge of the ruby language\&. If you don�t already know ruby, ruby is a well designed, \fIfully\fR 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)\&.
+
+.PP
+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/�\&. 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\~?? for how to add new elements, particles, macros etc\&.
+
+.PP
+The user configuration directory should look like this:
+
+.TP 3
+\(bu
+~/\&.deplate/
+
+.RS
+.TP 3
+\(bu
+config\&.rb (the general user configuration file, which is loaded last)
+.TP
+\(bu
+deplate\&.ini (an alternative way to configure deplate)
+.TP
+\(bu
+after/ (files that are loaded right after the corresponding formatter or module)
+
+.RS
+.TP 3
+\(bu
+fmt/
+.TP
+\(bu
+input/
+.TP
+\(bu
+mod/
+.LP
+.RE
+.IP
+.TP
+\(bu
+css/ (user defined css files)
+.TP
+\(bu
+fmt/ (user defined formatters)
+.TP
+\(bu
+input/ (user defined input definitions)
+.TP
+\(bu
+lib/ (user defined deplate snippets)
+
+.RS
+.TP 3
+\(bu
+FORMATTER/ (output\-format specific deplate snippets)
+.LP
+.RE
+.IP
+.TP
+\(bu
+mod/ (user defined modules)
+.TP
+\(bu
+templates/ (user defined templates)
+.LP
+.RE
+.IP
+.LP
+
+.PP
+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\&.
+
+.PP
+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\&.
+
+.PP
+In general, configuration is done by patching ruby classes\&. In the following example, we
+
+.TP 3
+\(bu
+restrict the markers for unordered lists to �#�
+.TP
+\(bu
+define Koma\-Script�s article class as the default latex class
+.LP
+
+.IP
+
+    class Deplate::List::Itemize
+        @rx = /^(([ \\t]+)(#)[ \\t]+)(\&.+)$/
+    end
+    
+    class Deplate::Formatter::LaTeX
+        @@latexDocClass = "scrartcl"
+    end
+    
+.PP
+Here is another example from my personal �after/fmt/latex\&.rb� file\&.
+
+.IP
+
+    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
+    
+.TP 3
+1.
+Add a usepackage statement to the preamble \-\- with optional arguments from the �suppl� variable: \fImarkup.xml#docCmd\fR\&.
+.TP
+2.
+extracts information about the document�s title and author (see\~??) and adds some user\-defined commands to the document preamble \-\- but below any usepackage statements (see\~??)
+.LP
+
+.SS "User configuration of the standard setup"
+
+.PP
+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\&.
+
+.PP
+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 (see\~??) or to permanently require one of deplate�s modules\&.
+
+.PP
+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\&.
+
+.IP
+
+        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
+        
+.SS "Configuration of wiki names"
+
+.PP
+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:
+
+.IP
+
+        class Deplate::HyperLink
+            @@uc = 'A\-Z���'
+            @@lc = 'a\-z��������������'
+        end
+        
+        # the following re\-compiles the regexps for wiki names
+        Deplate::HyperLink\&.setup
+        
+.SS "Configuration via deplate.ini"
+
+.PP
+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\-\-but see\~[xref to refsect1]\&.
+
+.PP
+This file contains a sequence of commands\&. Each command must fit in one line\&. The following commands are allowed:
+
+.TP
+mod\~NAME
+Load the module NAME
+
+.TP
+fmt\~NAME
+Set the standard formatter
+
+.TP
+clip\~NAME=VALUE
+Set the clip NAME (e\&.g\&., �author�) to VALUE
+
+.TP
+wiki\~NAME\&.SUFFIX=BASEURL
+Define an interwiki (the \&.SUFFIX part is optional)
+
+.TP
+wikichars\~UPPERCHARS\~LOWERCHARS
+Define the allowed characters in wiki names
+
+.RS
+.Sh "Important"
+
+.PP
+Wiki names must always begin with A\-Z even then wiki chars were redefined (at least until ruby�s regexp library makes \\b match properly against words starting with an international upper case character)
+
+.RE
+
+.TP
+app\~NAME=COMMANDLINE
+Define an external app (e\&.g\&., latex, dvips, R, dot, neato, pstoedit, identify, gs \&.\&.\&.)
+
+.TP
+$ENV=VALUE
+Set an environment variable
+
+.TP
+VAR=VALUE
+Set variable VAR to VALUE
+
+.RS
+.TP 3
+\(bu
+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\&.
+.LP
+.RE
+.IP
+
+.PP
+Although this may not always work as expected, you can also set some options (as defined in \~??) by prepending the name with a colon (�:�) or by using the option keyword:
+
+.TP
+option\~NAME~
+Set option NAME to false
+
+.TP
+option\~NAME!
+Set option NAME to true
+
+.TP
+option\~NAME?=true|false|yes|no|on|off
+Set option NAME to a boolean value
+
+.TP
+option\~NAME%=INTEGER
+Set option NAME to a numeric value
+
+.TP
+option\~NAME=VALUE
+Set option NAME to VALUE as string
+
+.PP
+Lines beginning with one of *%#; are considered comments\&.
+
+.PP
+Example deplate\&.ini:
+
+.IP
+
+        # Load some standard modules
+        mod de
+        mod mark\-external\-urls
+        mod colored\-log
+        
+        # Applications
+        app dot=/somewhere/not/in/the/standard/path/dot
+        
+        # Clips
+        clip author=Thomas Link
+        
+        # Options
+        option allow_exec!
+        option allow_ruby!
+        
+        # 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
+        
+.SS "Templates"
+
+.PP
+deplate supports two ways of page templates:
+
+.TP 3
+1.
+Template variables
+.TP
+2.
+Template files
+.LP
+
+.PP
+You can define a template in ruby by setting the following Deplate class variables:
+
+.TP 3
+\(bu
+these variables (array of arrays of strings) can be redefined in Deplate::Core\&.user_setup to put some formatted output on every page/file
+
+.RS
+.TP 3
+\(bu
+@@pre_matter_template
+.TP
+\(bu
+@@body_template
+.TP
+\(bu
+@@post_matter_template
+.LP
+.RE
+.IP
+.TP
+\(bu
+this variable (array of strings) can contain some deplate markup that will be prepended to every file read
+
+.RS
+.TP 3
+\(bu
+@@deplate_template
+.LP
+.RE
+.IP
+.LP
+
+.PP
+Typical use would be (in your config\&.rb file)
+
+.IP
+
+            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
+            
+.PP
+Via the \-t or \-\-template command\-line option or by setting the template document variable (see\~??), you can define simple text templates that will be filled in with content from your deplate file\&.
+
+.PP
+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: \fImarkup.xml#docOpt\fR  template_version to 1\&.
+
+.PP
+In templates, only a small number of statements are available:
+
+.TP
+Commands
+GET, ARG, XARG, VAR, OPT, PREMATTER, POSTMATTER, BODY, IF, ELSE, ELSEIF, ENDIF, INC/INCLUDE
+
+.TP
+Regions
+Foreach, Mingle, Ruby, Var
+
+.TP
+Macros
+get, clip, opt, arg, xarg, doc, ruby
+
+.PP
+The commands PREMATTER, POSTMATTER, BODY as well as the Mingle region are specific to templates\&.
+
+.PP
+PREMATTER, POSTMATTER, and BODY can be used to fill in formatted content (see\~?? for an explanation of deplate�s document structure):
+
+.TP
+#PREMATTER
+The file header, the beginning of the document definition, some text that in multi\-file mode should appear in every output file
+
+.TP
+#BODY
+The text body
+
+.TP
+#POSTMATTER
+Some text that in multi\-file mode should appear in every output file, the end of document definition
+
+.PP
+These commands take a list of slots (named or as numbers) as arguments (see\~??)\&. The slots can be single slots or ranges\&. They can be positive (add selectively) or negative (add with the exception of certain content)\&. Examples:
+
+.TP
+#PREMATTER:\~\-doc_def
+add the prematter without the document type definition
+
+.TP
+#PREMATTER:\~doc_def\~mod_packages\~mod_head
+add the document type definition, and stuff added by modules
+
+.TP
+#PREMATTER:\~head_beg\&.\&.prematter_end
+add everything from the head on downwards
+
+.PP
+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\&.
+
+.PP
+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\&.
+
+.PP
+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\&.
+
+.PP
+Backslashes have always to be doubled\&.
+
+.PP
+A LaTeX template could then look like this:
+
+.IP
+
+            
+            \\\\documentclass[12pt,a4paper]{letter}
+            
+            #PREMATTER: \-doc_def
+            
+            \\\\address{{get: author}\\\\\\\\
+                Where I live}
+            \\\\signature{{get: author}}
+            
+            \\\\begin{letter}{{get: addresseeAddress}}
+                
+            \\\\opening{Dear {get: addresseeName},}
+            
+            #BODY
+            
+            \\\\closing{Sincerly,}
+            
+            \\\\vfill{}
+            \\\\encl{{val: enclosure}}
+            
+            \\\\end{letter}
+            
+            #POSTMATTER
+            
+.PP
+You could now copy this example template to �~/\&.deplate/templates/letter\&.tex� and call deplate as:
+
+.IP
+
+            deplate \-f latex \-t letter\&.tex DEPLATE\&.FILE
+