'\" -*- coding: us-ascii -*-
.if \n(.g .ds T< \\FC
.if \n(.g .ds T> \\F[\n[.fam]]
.de URL
\\$2 \(la\\$1\(ra\\$3
..
.if \n(.g .mso www.tmac
.TH wiki2beamer 1 "9 May 2011" "" ""
\fBwiki2beamer\fR(1)
.SH NAME
wiki2beamer \- convert wiki-formatted text to latex-beamer code
.SH SYNOPSIS
'nh
.fi
.ad l
\fBwiki2beamer\fR \kx
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
'in \n(.iu+\nxu
[\fIOPTION\fR | \fIFILE\fR\&...]
'in \n(.iu-\nxu
.ad b
'hy
.SH DESCRIPTION
.TP 
\fIFILE\fR
the text-file(s) to be processed
.TP 
\*(T<\fB\-h\fR\*(T> \*(T<\fB\-\-help\fR\*(T>
show a short usage help
.TP 
--version
show version information
.SH USAGE
Usually you want to pipe the output of wiki2beamer into a file:
.PP
\*(T<wiki2beamer footalk.txt > footalk.tex\*(T>
.PP
If called without any input file, wiki2beamer reads input from STDIN. If called with multiple
input files, wiki2beamer reads and processes them in order with their content beeing simply concatenated. 
.PP
If an error occurs, wiki2beamer returns a return code other then 0.
.SH SYNTAX
Wiki2beamer has it's own wiki-syntax which (evolved without much of a concept ;) and) is described below.
Everything that is unknown to wiki2beamer will be passed through to the LaTeX output
(unless inside special environments).
.SS "OVERALL STRUCTURE"
A wiki2beamer txt file can consist of two sections: the head and the body.
The head is optional and is an autotemplate environment.
The body contains the content of the document. If the head (autotemplate) is not given,
then only the code for the body will be generated and can be included into a manually crafted
LaTeX template file.
.SS "MANAGING INPUT"
You can split input to wiki2beamer into multiple files. This helps to keep things appart and avoids conflicts.
There are two ways to split input. The first is to use multiple input files which wiki2beamer will read and process in order as
if they were one concatenated file. The second is to use the >>>include<<< syntax.
.TP 
>>>\fIincludefile\fR<<<
Include the file named \fIincludefile\fR at this line. Works recursively. Endless recursion
will be detected and treated as an error. Including files doesn't work inside [nowiki] and [code] environments
(see below).
.SS "STRUCTURING THE PRESENTATION"
.TP 
== \fIsectionname\fR ==
opens a section called \fIsectionname\fR
.TP 
== \fIlongsectionname\fR ==[\fIshortname\fR]
opens a section called \fIlongsectionname\fR, 
passing the parameter \fIshortname\fR to latex
.TP 
=== \fIsubsectname\fR ===
opens a subsection called \fIsubsectname\fR
.TP 
=== \fIlongsubsectname\fR ===[\fIshortname\fR]
opens a subsection called \fIlongsubsectname\fR,
passing the parameter \fIshortname\fR to latex
.TP 
==== \fIframetitle\fR ====
opens a frame with the title \fIframetitle\fR
.TP 
==== \fIframetitle\fR ====[\fIparam\fR]
opens a frame with the title \fIframetitle\fR,
passes frame \fIparam\fReters like t, fragile, verbatim etc. to latex
.TP 
!==== \fIframetitle\fR ====[\fIparam\fR]
the ! added in front of a frame, selects a frame for exclusive generation.
It makes wiki2beamer skip all frames that are not selected.
You can select multiple frames. This can speed up the edit-compile-view cycle massively.
.PP
Sectioning commands work only at the beginnig of a line.
.SS "LISTS (BULLETS/ENUMERATIONS)"
.TP 
* \fItext\fR
create a bullet (itemize) with \fItext\fR
.TP 
*<\fIonslide\fR> \fItext\fR
create a bullet (itemize) with \fItext\fR that only
appears on the specified slides (\fIonslide\fR)
.TP 
# \fItext\fR
create a numbered item (enumerate) with \fItext\fR
.TP 
#<\fIonslide\fR> \fItext\fR
create a numbered item (enumerate) with \fItext\fR that only
appears on the specified slides (\fIonslide\fR)
.PP
Cascaded lists, mixed ordered and unorderd items:

.nf
\*(T<
	* This is a crazy list.
	*# It contains different items.
	*# In different formats.
	*** On different levels.
	***<2\-> which are animated
	*<3\-> Quite a lot of fun.
	**<4\-> Isn't it?
	\*(T>
.fi
.SS ENVIRONMENTS
LaTeX knows many environments, some of which are as simple as \ebegin{center} \eend{center}, others are more complicated.
To use these in a more wiki-like fashion, use <[name] to open and [name]> to close environments. It will
be simply converted to \ebegin{name} and end{name}.
.RS 
\fBWarning\fR

No parsing is done. The user is responsible for closing any opened environment. Environment-tags are only recognized at the beginning of a line.
.RE
.SS "SPECIAL ENVIRONMENTS"
Unlike standard environments, some environment names are recognized by wiki2beamer.
These are: nowiki, code, autotemplate and frame. If wiki2beamer detects one of these it will do some advanced
parsing, which can even fail with a syntax error.
.SS AUTOTEMPLATE
Autotemplate can be used at the beginning of a beamer .txt file. It will create the required
LaTeX headers to compile the content.
.TP 
<[autotemplate]
opens the autotemplate environment
.TP 
[autotemplate]>
close the autotemplate environment
.TP 
\fIkey\fR=\fIvalue\fR (inside [autotemplate])
insert a template command \e\fIkey\fR\fIvalue\fR
.PP
key=value pairs are converted to \ekeyvalue in the output
(except special keys) -- everything after = is just appended to \ekey.

.nf
\*(T<<[autotemplate]
usepackage=[utf8]{inputenc}
[autotemplate]>\*(T>
.fi

will be converted to \eusepackage[utf8]{inputenc}.
.PP
There is a built-in set of options:

.nf
\*(T<<[autotemplate]
documentclass={beamer}
usepackage={listings}
usepackage={wasysym}
usepackage={graphicx}
date={\etoday}
lstdefinestyle={basic}{....}
titleframe=True
[autotemplate]>\*(T>
.fi

titleframe is a special key that tells wiki2beamer to create a title frame. To set the title, subtitle and author of the presentation
use the keys title, subtitle and author. Overriding of the default options works on
.TP 0.2i
\(bu
per-key level for: documentclass, titleframe
.TP 0.2i
\(bu
per-package level for: usepackage
.TP 0.2i
\(bu
no overriding for: everything else
.SS CODE
Use code-environments to display animated code listings.
.TP 
<[code]
open a code environment
.TP 
<[code][\fIparam\fR]
open a code environment passing \fIparam\fReters
to the latex lstlisting environment.
.TP 
[code]>
close the code environment
.PP
.nf
\*(T<
			<[code][key=value,...]
			...
			[code]>
			\*(T>
.fi

<[code] opens the environment, [code]> closes it, everything after <[code] is passed
to the LaTeX listings package as options for this listing.
Inside the code environment, [ and ] must be escaped as \e[ and \e]. Things between [ and ] are animations.
There are two kinds of animations:
.TP 0.2i
\(bu
[<slidespec>some code] - show "some code" only on specified slides
.TP 0.2i
\(bu
[[<slidespec>some code][<slidespec>some other code]] - show "some code"
on the slides in the first spec, show "some other code" on the slides in the second spec, fill up space
on slides without content with spaces
.PP
Slide-specs can be of the form:
.TP 0.2i
\(bu
n - one single frame n
.TP 0.2i
\(bu
n-m - sequence of frames n to m
.TP 0.2i
\(bu
spec,spec,... - combine multiple specs into on (e.g. <1-3,5>)
.SS NOWIKI
Nowiki-Environments completly escape from wiki2beamer replacements. <[nowiki] opens the environment, [nowiki]> closes it.
.SS FRAME
The LaTeX-frame environment is where the content of a slide goes.
You can manually close a frame-environment which was opened with ==== Frametitle ==== with [frame]>.
Wiki2beamer is then aware that the last frame is already closed and doesn't try to close it again.
.SS "TEXT FORMATTING"
.TP 
\&'''\fItext\fR'''
typeset \fItext\fR bold
.TP 
\&''\fItext\fR''
typeset \fItext\fR italic
.TP 
@\fItext\fR@
typeset \fItext\fR in typewriter type, to ignore an @, escape it as \e@
.TP 
!\fItext\fR!
alert \fItext\fR, to ignore and !, escape it as \e!
.TP 
_ \fIcolor\fR _ \fItext\fR _
make \fItext\fR appear in \fIcolor\fR
.SS COLUMNS
.TP 
<[columns]
opens the column environment
.TP 
[[[ \fIwidth\fR ]]]
creates a column of \fIwidth\fR, everything below goes into this column
.TP 
[columns]>
closes the column environment
.SS GRAPHICS
.TP 
<<<\fIpathtofile\fR>>>
include image from \fIpathtofile\fR
.TP 
<<<\fIpathtofile\fR,\fIkey=value\fR>>>
include image from \fIpathtofile\fR passing \fIkey=value\fR
parameters to latex
.SS FOOTNOTES
.TP 
(((\fItext\fR)))
create a footnote containing \fItext\fR
.SS LAYOUT
.TP 
--\fIlength\fR--
when found at start of line, with nothing afterwards,
insert a \evspace{\fIlength\fR} (vertical space of length
\fIlength\fR)
.TP 
--*\fIlength\fR--
same as above, but insert a \evspace* (a forced vspace)
.TP 
+<\fIoverlay\fR>{\fIcontent\fR}
\euncover the \fIcontent\fR on the given \fIoverlay
\fRsubframes. They will allready take up the space, they need to be displayed, so the geometry of the frame doesn't change when the element pops up.
.TP 
-<\fIoverlay\fR>{\fIcontent\fR}
\eonly show the \fIcontent\fR on the given \fIoverlay
\fRsubframes. They will not take up the space they need to be displayed, so the geometry of the frame changes when the element pops up.
.SS SUBSTITUTIONS
.TP 
-->
becomes $\erightarrow$
.TP 
==>
becomes $\eRightarrow$
.TP 
<--
becomes $\eleftarrow$
.TP 
<==
becomes $\eLeftarrow$
.TP 
:-)
becomes \esmiley (requires package wasysym)
.TP 
:-(
becomes \efrownie (requires package wasysym)
.SS "FRAME HEADERS/FOOTERS"
There are two variables, FRAMEHEADER and FRAMEFOOTER. The content of these will be inserted at the beginning/end of all following slides.
.TP 
@FRAMEHEADER=\fItext\fR
set frameheader to \fItext\fR
.TP 
@FRAMEFOOTER=\fItext\fR
set framefooter to \fItext\fR
.PP
Leave \fItext\fR empty to reset frame headers and footers.
.SH LICENSE
Copyright (C) 2009 Kai Dietrich, Michael Rentzsch and others.
.SS "DOCUMENTATION LICENSE"
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
.SS "CODE LICENSE"
wiki2beamer is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 2 of the License, or
(at your option) any later version.