DragonFly On-Line Manual Pages

Search: Section:  


DEPLATE(1)                                                          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: 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-ZAOU' @@lc = 'a-zaoussaaeeiioocn' 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-ZAOU a-zaoussaaeeiioocn 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 Strasse 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)

Search: Section: