intro.txt

% vi: ft=viki:tw=72
% @Last Change: 2009-04-05.

* Introduction
#OPT: id=Introduction
#LIST fmt=html plain! sub!: toc

#INC: blurb.txt

In case deplate doesn't meet your needs, there are plenty of similar 
tools you might want to give a try.

For converting mostly plain text to HTML, LaTeX etc.:
    - [[http://www.maplefish.com/todd/aft.html][aft]]
    - [[http://www.methods.co.nz/asciidoc/][asciidoc]]
    - [[http://johnmacfarlane.net/pandoc/][pandoc]]
    - [[http://mercnet.pt/plaindoc/pd.html][PlainDoc (pd2tex)]]
    - [[http://docutils.sourceforge.net/rst.html][reStructuredText]]
    - [[http://raa.ruby-lang.org/project/sisu/][sisu]]
    - [[http://txt2tags.sourceforge.net][txt2tags]]
    - [[http://yodl.sourceforge.net][yodl]]

With respect to website generation, you might also be interested in 
these tools:
    - [[http://raa.ruby-lang.org/project/webgen/][webgen]]
    - [[http://raa.ruby-lang.org/project/rote/][rote]]

The authors of zoem (Stijn van Dongen and Joost van Baal) compiled a 
comprehensive list of
[[http://micans.org/zoem/ecosphere.html][similar efforts]].


** Goals

    # Use it as a personal wiki (via the 
      [[http://www.vim.org/scripts/script.php?script_id=861][Vim viki plugin]])
    # Be able to publish to many other formats -- but do it in a way so 
      that the output looks nice and can be edited and shared with other 
      people
    # Use a syntax that is convenient to use with all sorts of 
      non-specialized text editors (the most basic markup should be 
      wiki-style; more complex things should be done using a more 
      structured approach or by embedding ruby code)
    # Support all the tags needed to write not-too-technical documents 
      (i.e., headings, footnotes, citations, indices, page 
      headers/footers, tables, figures, verbatim text, basic text styles 
      etc.)
    # Conditionally allow the dynamic/on-the-fly generation of content 
      (e.g., statistical analyses via R, concept maps via dot ...)
    # Use other programs for tasks they perform well
    # Make it customizable


% ** Genesis
% 
% In the beginning, there was a word: LaTeX. Then, there was a second 
% word: Deppert. Together it was: Depperts LaTeX, which, in English, means 
% something like "LaTeX sucks".  So the word "\DepLate" was born, which was 
% funny because this word was originally (one week earlier) spelled 
% \DePlaTe, which means de(or undo)-plain-text.


* Getting ''deplate''
#OPT: id=GettingDeplate
#LIST fmt=html plain! sub!: toc

** Requirements

    [[http://www.ruby-lang.org][Ruby interpreter]] :: ''deplate'' was 
      tested with Ruby/Cygwin {ruby: VERSION} under WinXP; the win32 
      binary was generated with exerb and doesn't require neither a ruby 
      interpreter nor the ''deplate'' sources to be installed
      #NOIDX: Ruby interpreter
      #IDX: Ruby|ruby

Optional (you only need these for certain tasks or if you want to use 
certain modules):

    [[http://www.tug.org/][LaTeX]], \
    [[http://www.radicaleye.com/dvips.html][dvips]], \
    [[http://www.cs.wisc.edu/~ghost/][Ghostscript]] :: 
      For support of inline LaTeX
      #IDX: dvips; Ghostscript|gs

    dvipng :: For rendering LaTeX snippets as png
      #IDX: dvipng

    kpsewhich (most likely part of your LaTeX distribution) :: For
      searching bibliography files
      #IDX: kpsewhich

    [[http://www.imagemagick.org/][Image\Magick]] :: The LaTeX-formatter 
      uses the ''identify'' tool to guess image dimensions if you don't 
      provide them; see also{ref: identify}

    [[http://code.whytheluckystiff.net/hpricot][hpricot]] :: HPricot is 
      required by [[modules#codeGvim][code-gvim71]] module.
      #IDX: GVIM|gvim

    [[http://www.jave.de][Jave]] :: For converting images to ASCII 
      representations to be used in plain text output.

    #DONTIDX: dot, neato
    [[http://www.research.att.com/sw/tools/graphviz/][dot, neato]] :: For 
      on-the-fly generation of figures and plots

    [[http://www.r-project.org][R]] :: For on-the-fly generation of 
      plots and tables
      #IDX: dot; neato; R

    [[http://asciimathml.sourceforge.net/][ASCIIMathML.js]] :: For use
      with the [[modules#asciimath][html-asciimath]] module

    [[http://www.math.union.edu/~dpvc/jsMath/][jsMath.js]] :: For use 
      with the [[modules#jsmath][html-jsmath]] module

    [[http://raa.ruby-lang.org/project/ansicolor/][Term::ANSIColor]] :: 
      For colored log output (when using the ''--color'' command line 
      option)

    [[http://mathml.rubyforge.org][mathml]] by KURODA Hiraku :: For 
      [[modules#mathmlgem][mathml]] in conjunction with the 
      [[formats#xhtml10t][xhtml10t]] output formatter.

    [[http://www.andre-simon.de/][highlight]] :: For syntax highlighting 
      (see{ref: codeHighlight} and {ref: codeRegion})

    [[http://www.vim.org][GVIM]] :: For syntax highlighting (see{ref: 
      codeGvim} and {ref: codeRegion}) and maybe also for editing :-)


#AUTOIDX: Open\Office; RTF|rtf
Under MS Windows, the [[http://www.cygwin.com][Cygwin]] environment 
comes with a convenient installer and provides ruby, latex, divps, gs, 
and Image\Magick.


** Download

This program is free software; you can redistribute it and/or modify
it under the terms of the [[LICENSE.txt][GNU General Public License]!] 
as published by the Free Software Foundation; either version 2 of the 
License, or (at your option) any later version.

Download the most current version from the sourceforge project site:
http://sourceforge.net/projects/deplate/

The win32 binary was created using 
[[http://exerb.sourceforge.jp/index.en.html][exerb]] and should work 
without ruby being installed. Be aware that some modules don't work with 
the win32 binary version.
    % !!! I'm currently not able to build the win32 executable with 
    %     ''exerb''.

If you have ruby installed, you might want to use the 
[[http://docs.rubygems.org/][rubygem]] version.


** Support

If you have any questions, please post them to the support forum at: 
http://sourceforge.net/forum/forum.php?forum_id=371484



* Installation
#OPT: id=Installation
#LIST fmt=html plain! sub!: toc

** Gem

This is the recommended way to install ''deplate''. Ruby and 
[[http://docs.rubygems.org/][rubygems]] have to be installed.

While connected to the internet:

#Verb <<---
gem install deplategem
---

Offline after having downloaded the 
[[http://rubyforge.org/frs/?group_id=126][gem package]]:

#Verb <<---
gem install deplate-VERSION.gem
---


** Win32

Copy the win32 executable to a directory included in the PATH variable.


** ZIP Archive

On the command line, go to the root directory of the deplate sources, 
where setup.rb resides.

#Verb <<---
cd PATHTODEPLATE
---

See which options are available.

#Verb <<---
ruby setup.rb --help
---

% Configuration options:
% 
%     ''--win32'' :: Install a windows batch file instead of a bash script

Setup the ruby library and the bash or batch script (depending on 
RUBY_PLATFORM). Copy the ruby files to ruby's site-lib directory, and 
the script to an appropriate directory in $PATH.

#Verb <<---
ruby setup.rb config
ruby setup.rb setup
ruby setup.rb install
---

or just:

#Verb <<---
ruby setup.rb
---

Check if the modules show up correctly. At the bottom of the help text, 
there is a list of available formatting backends and modules. If this 
list is empty, something went wrong.

#Verb <<---
deplate --help
---

In case something goes wrong, here are the starter scripts. As shell 
script

#Verb <<---------
#!/usr/bin/env ruby
require 'deplate'
Deplate::Core.deplate
---------

and as batch script:

#Verb <<---------
@echo off
ruby -rdeplate -e Deplate::Core.deplate -- %*
---------

If you use an "older" version of MS Win & command.exe instead of 
cmd.exe, you might have to replace ''%*'' with ''\%1 \%2 \%3 \%4 \%5 \%6 
\%7 \%8 \%9''.

% You might also want to copy the manual page into a directory in 
% $MANPATH.
% #Verbatim <<---
% cp man/man1/deplate.1 /usr/local/man/man1
% ---

In case you want to customize deplate, you should also build the api 
documentation.

#Verb <<---
rdoc -S -N lib/deplate
---

This will install the following files/directories:

    - ''[RUBY_BIN]/deplate[.bat]''
    - ''[RUBY_SITELIB]/deplate.rb''
    - ''[RUBY_SITELIB]/deplate/...''

''setup.rb'' doesn't provide an automatic uninstall routine. In order to 
remove ''deplate'' from your harddisk, you can either remove these 
directories and files by hand or you could try the following command:

#Verb <<---
rm -fv `cat InstalledFiles`
---

This requires of course that you keep the file "\InstalledFiles" which 
is generated during installation.


** Initial configuration

You might want to create a file ''~/.deplate/deplate.ini'' and add a few 
options (see{ref: configuration} for details). If you always trust your 
source files, I'd suggest to allow ''all''. You might also want to 
define a set of characters that form wiki names. The file could look 
like this:

#Verb id=deplateIniInitial syntax=dosini <<--
allow all
wikichars A-ZÄÖÜ a-zäöüßáàéèíìóòçñ
--


** Related Software

    [[http://rubyforge.org/projects/dokkit/][dokkit]] :: A document 
      generator by Andrea Fazzi.