<[autotemplate]
title={The wiki2beamer example}
[autotemplate]>

== Introduction ==

==== Welcome ====

Welcome to the wiki2beamer example presentation. We will do our best to
document and demonstrate all features of wiki2beamer in this file. It is not
meant to be a reference though, that will be the man page wiki2beamer(1).

==== Design goals ====

Wiki2beamer was written to make typesetting presentations with \LaTeX and
beamer easier. \LaTeX beamer can create beautiful presentations but it's
a very verbose language and most of the simple tasks like using frames or
bullet lists take an awfull amount of code that looks really complicated.
This often scares away beginners and
fellow colleagues from even starting with \LaTeX. This is where wiki2beamer
steps in. It's designed to make the start easier and not remove any of the
powers of the language.

== Basic usage ==

=== Commandline ===
==== Commandline usage ====
Wiki2beamer is written in python and known to work on python 2.3 up to 2.6.
You can use it on Windows too, if you have the python interpreter installed
properly.

On *nix environments you would simple use it like this:
<[code][style=basic]
wiki2beamer example.txt > example.tex
[code]>

On Windows you would have to call the python interpreter with the wiki2beamer
script:
<[code][style=basic]
python wiki2beamer example.txt > example.tex
[code]>


=== The big picture ===

==== The big picture ====
A latex beamer document consists (like any latex document) of some introductory
style definitions and the document body. In plain latex it looks like this:

<[code][style=basic]
\documentclass{beamer}
    %do some style-magic here
\begin{document}
    %insert your presentation here (body)
\end{document}
[code]>
wiki2beamer can produce both: only the body content of the presentation or a complete document.

==== body-only ====
If you want full control over all the fancy stuff you can do with latex, you
can use wiki2beamer to generate a .tex that that you can include with
@\textbackslash input\{filename.tex\}@.

<[code][style=basic]
\documentclass{beamer}
\begin{document}
    \input{w2b-output.tex}
\end{document}
[code]>

This is the default mode of operation.

==== autotemplate ====
If you want wiki2beamer to generate a complete document with header, you can
use the autotemplate feature. It's a special environment in wiki2beamer
syntax and must be the first element in the input file. It has a simple
@key=\{value\}@ syntax. For a full reference see the man page.

<[code][style=basic]
<\[autotemplate\]
title={The Title}
author={Mr. Foo Bar}
date={1970-01-01}
titleframe=False
\[autotemplate\]>
[code]>

If the autotemplate environment is used, a default titleframe is generated. If
you want that disabled, you can switch it with the titleframe option.

=== Structure and frames ===

==== Structure and frames ====

As most wiki-dialects, wiki2beamer supports the famous

<[center]
@==== title ====@
[center]>

syntax. When these markings start at the beginning of a line, wiki2beamer
expands them to open a frame.

==== Structure and frames ====

The following heading markups exist:

--1em--

@== title ==@ --> opens a section

--1em--

@=== title ===@ --> opens a subsection

--1em--

@==== title ====@ --> opens a frame

--1em--

Frames will be closed automatically when a new sectioning or frame markup
appears. Frames can also be closed with an optional @[frame]>@ marking
(usually only needed to write advanced LaTeX code between frames).

[frame]>

% now you can put your fancy LaTeX code here (outside of a frame)

=== Lists ===

==== Lists ====

Probably one of the most used text elements in presentations
are:
* bullet
* lists
and
# numbered
# lists

==== Bullet Lists ====

Bullet lists can be created by prepending one or many @*@ before a line
<[code][style=basic]
* A simple bullet list
* with two items
[code]>

Bullet list can also be multi-level:
<[code][style=basic]
* A more complex bullet list
** with a sublist
** and another sublist
*** here
[code]>

==== Bullet Lists (output) ====

* A simple bullet list
* with two items

* A more complex bullet list
** with a sublist
** and another sublist
*** here


==== Numbered Lists ====

The same works for numbered lists
<[code][style=basic]
# first item
# second item
## with two subitems
## and onother
### subsubitem
# third item
[code]>

==== Numbered Lists (output) ==== 

# first item
# second item
## with two subitems
## and onother
### subsubitem
# third item

==== Mixed Lists ====

Numbered and bullet lists can be mixed:
<[code][style=basic]
# first item
#* with a sub-list
#*# one numbered subsub-item
#*# another numbered subsub-item
#* and a lone bullet
# second item
[code]>

==== Mixed Lists (output) ====

# first item
#* with a sub-list
#*# one numbered subsub-item
#*# another numbered subsub-item
#* and a lone bullet
# second item

=== Text markup ===

==== Text markup ====

Text can be formatted with some markups. Some markups can be escaped with a
\textbackslash.

\begin{tabular}{|l|l|l|}
\hline
markup & output & escaping \\\hline
\hline
<[nowiki]
\texttt{'''bold text'''}
[nowiki]>
	& '''bold text''' & \\\hline
<[nowiki]
\texttt{''italic text''}
[nowiki]>
	& ''italic text'' & \\\hline

<[nowiki]
\texttt{@teletype text@}
[nowiki]>
	& @teletype text@ & \textbackslash@ \\\hline

<[nowiki]
\texttt{!alerted text!}
[nowiki]>
	& !alerted text! & \textbackslash! \\\hline

<[nowiki]
\texttt{\_color\_colored text\_}
[nowiki]>
	& _blue_blue text_ & \\\hline
\end{tabular}

==== Text substitutions ====

There are some simple text replacements you can use:

--2em--

\begin{tabular}{|l|l|l|}
\hline
markup & output & escaping \\\hline
\hline
<[nowiki]
\texttt{-->}
[nowiki]>
	& --> & \\\hline
<[nowiki]
\texttt{<--}
[nowiki]>
	& <-- & \\\hline
<[nowiki]
\texttt{==>}
[nowiki]>
	& ==> & \\\hline
<[nowiki]
\texttt{<==}
[nowiki]>
	& <== & \\\hline
<[nowiki]
\texttt{:-)}
[nowiki]>
	& :-) & \\\hline
<[nowiki]
\texttt{:-(}
[nowiki]>
	& :-( & \\\hline
\end{tabular}


==== Footnotes ====

You can also use footnotes on your slides(((This is such a footnote.))).

--2em--

<[code][style=basic]
...your slides(((This is such a footnote.))).
[code]>

=== Environments ===

==== Environments ====
One of the basic building blocks of LaTeX syntax are environments. In plain
LaTeX you open, give options and close them with the following notation:
<[code][style=basic]
\begin{someenv}\[option=foo\]
...
\end{someenv}
[code]>

wiki2beamer provides a shorter syntax that looks like this:
<[code][style=basic]
<\[someenv\]\[option=foo\]
...
\[someenv\]>
[code]>

==== Environment example ====

Some of the most used environments probably is:

--1em--

<[nowiki]
\texttt{
<[center]
some centered text
[center]>
}
[nowiki]>

--1em--

output:

--1em--

<[center]
some centered text
[center]>

==== LaTeX vs. wiki2beamer environments ====

The default case is that wiki2beamer doesn't care about the name of the
environment and just passes it on to LaTeX.
For these default environments wiki2beamer doesn't track
open and close tags.
--1em--
There are a few exceptions where wiki2beamer knows and parses the
environments:
* @[nowiki]@ (escaping from wiki2beamer)
* @[code]@ (code listings)
* @[autotemplate]@ (autotemplate header)


=== Escaping ===

==== Escaping from wiki2beamer ====

Everything wiki2beamer doesn't know, it doesn't touch. But what if it knows
something that you want it to leave untouched?

For some of the most common notations we already have escaping with a
\textbackslash. If there isn't an escape, you can use the generic
@[nowiki]@ environment.

<[code][style=basic]
<\[nowiki\]
'''text that isn't bold'''
\[nowiki\]>
[code]>

Notice that the [nowiki] tags start and end at the beginning of a line.

==== Escaping (output) ====

<[nowiki]
'''text that isn't bold'''
[nowiki]>

=== Code ===

==== Code ====

One of the great strengths of LaTeX is the ability to typeset and highlight
sourcecode. Doing that manually is a very tedious task in visual presentation
tools. In LaTeX code listings are realized with the @listings@ package that
provides a new @\textbackslash lstlisting@ environment.
--1em--
In wiki2beamer we have a convenient @[code]@ environment.

==== Code ====

The basic usage is:
<[code][style=basic]
<\[code\]
... your listing here ...
\[code\]>
[code]>

The @lstlisting@ environment in the background provides options, e.g. you can
configure the highlighting:
<[code][style=basic]
<\[code\]\[style=basic,language=C,title=code example\]
if ( a == b ) { return 0; }
\[code\]>
[code]>

Inside @[code]@ environments, wiki2beamer processing is mostly disabled. The
only characters with a special meaning are @[@ and @]@ which have to be
escaped with a \textbackslash.

==== Code (output) ====

<[code][style=basic,language=C,title=code example]
if ( a == b ) { return 0; }
[code]>


=== Layout ===

==== Vertical Space ====

You can insert vertical space between two paragraphs with the

<[center]
<[nowiki]
\texttt{--length--}
[nowiki]>
[center]>

notation where ''length'' can be a valid latex length expression (e.g. @1cm@, @1pt@, @1em@ or even
@0.2\textbackslash textwidth@). This space will be squeezed by latex when the
page is full. To really force LaTeX to insert a space, use the
alternative

<[center]
<[nowiki]
\texttt{--*length--}
[nowiki]>
[center]>

notation.



==== Columns ====
Latex beamer can devide the current frame into collumns.
In wiki2beamer this can be done with the following notation:
<[code][style=basic]
<\[columns\]

\[\[\[width\]\]\]
this is the first column

\[\[\[width\]\]\]
this is the second column

\[columns\]>
[code]>

where ''width'' is a valid latex length expression.

==== Columns example ====
<[code][style=basic]
\centering
Text above the columns

<\[columns\]

\[\[\[0.4\textwidth\]\]\]
this is:
* the first column
* with a list

\[\[\[0.4\textwidth\]\]\]
this is:
* the second column
* with another list

\[columns\]>

\centering
Text below the columns
[code]>


==== Columns example (output) ====
\centering
Text above the columns.

<[columns]

[[[0.4\textwidth]]]
this is:
* the first column
* with a list

[[[0.4\textwidth]]]
this is:
* the second column
* with another list

[columns]>

\centering
Text below the columns.


=== Headers and Footers ===

==== Headers and Footers ====
Sometimes you want to repeat some latex code at the header and footer of your
presentation frames (e.g. to show logos or names). To make this easier you can
fill two special storage field @\@FRAMEHEADER=@ and @\@FRAMEFOOTER=@ with some
latex code. wiki2beamer will append or prepend this right after the frame
opening or frame closing in the resulting latex code.

@FRAMEHEADER=\begin{flushright}This is a generated FRAMEHEADER\end{flushright}
@FRAMEFOOTER=\vfill \begin{flushright}This is a generated FRAMEFOOTER\end{flushright}

==== Frame with generated header/footer ====

This is the text of the frame

%deleting header and footer
@FRAMEHEADER=
@FRAMEFOOTER=

== Graphics ==
==== Including graphics ====
LaTeX can include graphics with the @\textbackslash includegraphics@ command.
To ease the use, wiki2beamer provides a simple syntax.

simple:
<[code][style=basic]
<<<graphicsfile.png>>>
[code]>

advanced:
<[code][style=basic]
<<<graphicsfile.png,option=foo>>>
[code]>

For a documentation of available options, take a look at the graphix package
documentation.

==== Graphics example ====

<[code][style=basic]
<<<db-rg1024.png,height=0.5\textheight>>>
[code]>

==== Graphics example (output) ====

<<<db-rg1024.png,height=0.5\textheight>>>

== Animation ==

=== How it works ===

==== Animation ====
LaTeX beamer provides facilities for generating
simple animated slides. Wiki2beamer provides some
shortcuts on top of the beamer class.
--1em--
LaTeX beamer has the notion of animation layers:
Whenever a frame contains an animation, it will consist of
consecutive numbered animation layers.

==== Layer specs ====
Whenever you animate something, you can specify that it should
appear or disappear on a certain animation layer. The notations
can look like this:
--1em--
\begin{tabular}{ll}
@<n>@   & a single layer ''n'' \\
@<n,m>@ & two layers ''n'' and ''m'' \\
@<n-m>@ & all layers between ''n'' and ''m'' \\
@<n-m,k>@ & all layers between ''n'' and ''m'' plus layer ''k'' \\
\end{tabular}

=== Animating lists ===

==== Animating lists ====
To animate a wiki2beamer list, just add a spec after the @*@ or @\#@
characters:

<[code][style=basic]
* always there (layer 1-4)
*<2> only on layer 2
*<2-3> on layer 2-3
*<2,4> on layer 2 and 4
[code]>

==== Animating lists (output) ====

* always there (layer 1-4)
*<2> only on layer 2
*<2-3> on layer 2-3
*<2,4> on layer 2 and 4

=== Animating anything ===

==== Animating anything ====

LaTeX knows the two commands @\textbackslash uncover@ and
@\textbackslash only@.
--1em--
@uncover@ shows and element on the given layers
while otherwise just displaying an invisible placeholder box.
In wiki2beamer this is denotated as:
<[center]
<[nowiki]
\texttt{+$<$n-m$>$\{content\}}
[nowiki]>
[center]>

here's an example:
<[code][style=basic]
above

+<2>{uncovered}

below
[code]>

==== @uncover@ example (output) ====

above

+<2>{uncovered}

below

==== @only@ example ====

@only@ makes an element appear whithout having a placeholder box before.
In wiki2beamer this is denoted as:
<[center]
<[nowiki]
\texttt{-$<$n-m$>$\{content\}}
[nowiki]>
[center]>

here's the example:
<[code][style=basic]
above

-<2>{only on 2}

below
[code]>

==== @only@ example (output) ====

above

-<2>{only on 2}

below


==== animating graphics ====

Animating graphics is nothing special.
Here is the example:

<[code][style=basic]
+<1>{
	<<<db-rg1024.png,width=0.4\textwidth>>>
}
+<2>{
	<<<db-rg1024.png,width=0.4\textwidth>>>
}
[code]>

==== animating graphics (output) ====

<[center]
+<1>{
	<<<db-rg1024.png,width=0.4\textwidth>>>
}
+<2>{
	<<<db-rg1024.png,width=0.4\textwidth>>>
}
[center]>

=== Animating code ===

==== Animating code ====
When talking about code listings, you often want things to appear or
disappear, step by step. In wiki2beamer, you can do that with a simple
notation(((Try to do it without wiki2beamer, you'll feel the pain ;) ))).

<[code][style=basic]
<\[code\]
some normal code above
\[<2-4>some code only on layer 2-4\]
\[\[<2>some code on layer 2\]\[<4>replaced on layer 4\]\]
some normal code below
\[code\]>
[code]>

==== Animating code (output) ====

<[code][style=basic]
some normal code above
[<2-4>some code only on layer 2-4]
[[<2>some code on layer 2][<4>replaced on layer 4]]
some normal code below
[code]>



== Advanced usage ==

==== Advanced usage ====

<[center]
Tricks for the adept.
[center]>

=== Frame options ===

==== Frame options ====

LaTeX supports giving arguments to opening frames. It looks like:
<[code][style=basic]
\begin{frame}\[someoption\]
[code]>

Such options can be added in wiki2beamer by appending them to the frame
opening:
<[code][style=basic]
==== frametitle ====\[someoption]
[code]>

One example are fragile frames.

==== Fragile frames ====
For some features to work (eg. verbatim content), latex beamer needs a frame
marked as fragile. In plain \LaTeX this would look like:
<[code][style=basic]
\begin{frame}\[fragile\]
...
\end{frame}
[code]>

This can be realized with wiki2beamer by simply appending a @[fragile]@ tag to the
frame header:

<[code][style=basic]
==== a fragile frame ====\[fragile\]
...
[code]>

==== a fragile frame ====[fragile]
This is such a fragile frame with some \verb-V#rb/\t|m t<xt- .


=== Short section names ===[short sectioning]

==== Short section names ====

The same notation that applies for frame options
can be used with sections. This is used to asign a short name of the section
for the table of contents.

<[code][style=basic,basicstyle=\tiny\ttfamily]
=== some section name that is mich too long ===\[long section name\]
[code]>

=== selective editing ===

==== Selective editing ====
When LaTeX documents become large and contain many inputs (graphics), the latex
compiler tends to be slow -- to slow for the edit-compile cycle.
--1em--
To speed things up a bit, wiki2beamer allows you to select single frames for
editing.
<[center]
<[nowiki]
\texttt{!==== frame title ====}
[nowiki]>
[center]>
--1em--
When there is at least one selected frame, all frames that are not selected
will be ommited from the LaTeX output.


=== Managing input ===

==== Managing input ====
If you want to work with your colleagues on a single presentation
you can (and should) of course use your favourite version control system,
but you'd still have to resolve conflicts. To reduce the number of conflicts,
wiki2beamer can build presentations from multiple input files.

==== Mulitple inputs by commandline ====

The first way is to use the commandline to concatenate multiple input files:
--1em--
<[code][style=basic]
wiki2beamer header.txt dave.txt debby.txt > talk.tex
[code]>





>>>includefile.txt<<<