\documentclass{article}
\usepackage{a4}
\usepackage[latin1]{inputenc}
\usepackage{verbatim}
\usepackage{hyperref}
\usepackage{graphicx}
\usepackage{longtable}


%\input{udmath}


\hypersetup{bookmarks, bookmarksopen,
  pdftitle={VYM - a tool for visual thinking },
  pdfauthor={Uwe Drechsel},    
  pdfsubject={map},
  pdfkeywords={map, tool},
  pdfpagemode={UseOutlines},                                 
  bookmarksopenlevel={1},   
  colorlinks={true},     
  linkcolor={blue},
  urlcolor={green},
  citecolor={red}} 


\newcommand{\vym}{{\sc vym }}
\newcommand{\ra}{$\longrightarrow$}
\newcommand{\la}{$\longleftarrow$}
\newcommand{\ua}{$\uparrow$}
\newcommand{\da}{$\downarrow$}
\newcommand{\key}[1]{[#1]}

\begin{document}
\title{
	\includegraphics[width=8cm]{vym-logo-new.png}
	\\
VYM \\ -- \\View Your Mind\\ {\small Version 1.8.0}}
\author{\textcopyright Uwe Drechsel  }


\maketitle

\newpage

\tableofcontents

\newpage

\section{Introduction}
\subsection{What is a \vym map?}
A \vym map (in short words {\em map}) is a tree like structure:
\begin{center}
	\includegraphics[width=12cm]{example1.png}
\end{center}
Such maps can be drawn by hand on a paper or flip chart and help to
structure your thoughts. While a tree like structure like above can be
drawn manually \vym offers much more features to work with such maps.
\vym is not another drawing software, but a tool to store and modify
information in an intuitive way. For example you can reorder parts of
the map by pressing a key or add various information like a complete
email by a simple mouse click.

Once you have finished collecting and organizing your ideas, you can
easily generate for example a presentation in Open~Office based on a
map.

\subsection{Why should I use maps? Time, Space and your Brain.}
\subsubsection*{Space}
A map can concentrate a very complex content on little space e.g. a
piece of paper. It helps to use both sides of your brain: the logical
side and also your creative side (e.g. by using pictures, colors and
keywords in a map, so called {\em anchors}).  It is a technique to
organize the way you think: It can help you by developing, sorting and
memorizing your thoughts. 

\subsubsection*{Time}
Because you just use keywords and drawings, it is much faster than good
old fashioned notes. Your brain memorizes things by associating them to
other things -- a map makes use of those connections and stimulates
new asccociations. 


\subsubsection*{Your Brain}
In 1960 the Prof. {\sc Roger Sperry} discovered that both hemispheres
of the human brain have different tasks (of course both of them
basically {\em can} do the same): 
\begin{center}
\begin{tabular}{|p{5.5cm}|p{5.5cm}|} \hline
	Left side & Right side \\ \hline
	\begin{itemize}
	   \item verbal speech and writing 
	   \item numbers
	   \item logical thinking
	   \item analyzing and details
	   \item science
	   \item linear thinking
	   \item concept of time
	\end{itemize} &
	\begin{itemize}
		\item body language
		\item visual thinking, day dreams
		\item intuition and emotion
		\item overview of things
		\item creativity
		\item art, music, dancing
		\item non-linear thinking, connecting things
		\item spatial awareness
	\end{itemize}     \\ \hline
\end{tabular}	
\end{center}
In our science oriented society we have learned to mainly rely on our
left side of the brain, the "rational" one. In other cultures,
especially like the native americans and other "old" cultures, the right
side is much more important. Maps are just one way to stimulate the
other side and make use of additional ressources we all have.


\subsection{Where could I use a map?}
Here are some examples, how you can use those maps
\begin{itemize}
    \item to prepare articles, papers, books, talks, \ldots
    \item to sort complex data
    \item to memorize facts, persons, vocabulary, \ldots
    \item to sort emails, files and bookmarks on your computer
    \item to moderate conferences
\end{itemize}

\subsection{What you shouldn't do with a map...}
A map drawn by somebody shows the way the author thinks. There is
no right or wrong in the way it is drawn, so there is no way to criticize
it. "It is, what it is" ({\sc F.~Lehmann}).

%\section{Tutorials}
%TODO

\subsection{Internet Ressources} 
A good starting point to learn more about maps in general is Wikipedia:
\begin{itemize}
	\item English: 
		\href{http://en.wikipedia.org/wiki/Mind_map}{http://en.wikipedia.org/wiki/Mind\_map}
	\item German: 
		\href{http://de.wikipedia.org/wiki/Mindmap}{http://de.wikipedia.org/wiki/Mindmap}
\end{itemize}




\section{Concept of \vym}
%TODO may add a general introduction here...
\subsection{Windows: mapeditor and noteeditor}
\vym uses two windows: an editor for the map itself and another one for
notes, which are part of the map. Let's call them {\em mapeditor} and
{\em noteeditor}: 
\begin{center}
	\includegraphics[width=8cm]{windows.png}
\end{center}
Usually you will work in the {\em mapeditor} by just adding new
branches, moving around and reordering them. The various ways to do this
will be explained in \ref{mapeditor}. You can store additional
information e.g. the content of a email easily in a {\em branch}: Just
type or copy\&paste it into the {\em noteeditor}. Working with notes is
explained in \ref{noteeditor}

\subsection{Menus and Context menus}
On top of each window you find the menubar. The options you find there
are similar to those you are used from other applications. Note that
many (and even more) options are availabe via {\em context menus}. Those
are available if you right-click onto an object in a map (on Mac~OS~X
Command-Click).

\subsection{Toolbars}
The toolbars in the mainwindows give quick access to many functions and
also visualize the state of an object. For example a part of of the map
can be hidden when the map is exported into an Open~Office presentation.
To show this the branch in the map will have a little cloud symbol,
which is also "switched on" in the toolbar.

Note that you can reposition all toolbars by simply grabbing them. For
example you can move the flags-toolbar from its original horizontal
position on top of the mapeditor to a vertical position on the right
side. You can even detach it and make it "float" separate from the other
windows. Or just insert it again at its original position.

\subsection{Maps}
The map itself has always a {\em mapcenter}.  The
mapcenter has {\em branches} just like the trunk of a tree. Each branch
in turn may have branches again.
\begin{center}
	\includegraphics[width=10cm]{branches.png}
\end{center}
We will call a branch directly connected to the mapcenter a {\em
mainbranch}, because it determines the position of all its child
branches.

The mapcenter and the branches all have a {\em heading}. This is the
text you see in the mapeditor. Usually it should just be one or a few
words, so that one can easily keep track of the whole map.


In the toolbar above the mapeditor you see various symbols.
\begin{center}
	\includegraphics[width=8cm]{default-flags.png}
\end{center}
These are called {\em flags} and can be used to mark branches in the
map, e.g. if something is important or questionable. 
There are also more flags set by \vym automatically to show additional
information, e.g. when a  exists for a  particular branch.

By default some of these flags are set exclusively e.g. when the 
"thumb-up" flag is set, then the "thumb down" is unset and vice
versa. You can change this default behaviour in the settings menu.

%TODO add info about toolbars e.g. undo/redo, ...

\section{Mapeditor} \label {mapeditor}
\subsection{Start a new map}
After \vym is started two windows will open: the mapeditor and the
noteditor. Usually you will work in both windows, but at the moment we
will just need the mapeditor. 

Select the mapcenter "New map" in the middle of the mapeditor by
left-clicking with the mouse. It will turn yellow to show that is
selected. There are several ways to add a new branch to the center:
\begin{itemize}
	\item Using the mouse: Open the context meny by clicking with the
	right mouse button (CTRL-Click on Mac) onto the
	mapcenter and choose Add \ra Add as child
	\item Press \key{Ins} or \key{A}
\end{itemize}
A new branch will appear and you will be able to type the heading of the
branch. Finish adding the new branch by pressing \key{Enter}.
%tipp
Sometimes it comes handy to add a new branch above or below the current
one. Use \key{Ins} together with \key{Shift} or \key{Ctrl}. It is also
possible to add a branch in such a way, that the current selection
becomes the child of the new branch, which is like inserting it {\em
before} the selection. This can be done using the context menu.

\subsection{Navigate through a map}
\subsubsection*{Select branches}
To select branches you can use the left button of your mouse or also the
arrow keys. Depending on the {\em orientation} of a branch type
\key{\la} or \key{\ra} to get nearer to the mapcenter or deeper
down into the branches. Within a set of branches, let's call them a 
{\em subtree}, you can use \key{\ua} and \key{\da} to go up and down. You can
also use \key{Pos1} and \key{End} to select the first and last branch.


\subsubsection*{Zoom a map}
While adding more and more branches the size of the map may become
bigger than the mapeditor window. You can use the scrollbars on the
right and the bottom of your mapeditor window to scroll, but it is
easier to just scroll using the left mouse button: Click onto the {\em
canvas} itself, the empty space somewhere between the branches. The
mouse pointer will change from an arrow to a hand, now move the visible
part of the map to show the desired part.

If you select branches using the arrow keys, the map will scroll
to ensure that the selected branch is always visible.

Working with huge maps, the {\em zoom}-function comes in handy: You can
use 
\begin{itemize}
	\item from the menu View \ra Zoom
	\item the toolbar buttons 
		\begin{center}
			\includegraphics[width=3cm]{zoom-buttons.png}
		\end{center}	
\end{itemize}	
The crossed magnifying lens resets the zoomed view to its original size.


\subsubsection*{Find Function} \label{findwindow}
With huge maps there is the need to have a
find function. Choose Edit \ra Find to open the Find Window:
\begin{center}
	\includegraphics[width=6cm]{find-window.png}
\end{center}	
The text you enter here will be searched in all the headings and also in
notes. Everytime you press the "Find"-button it will look for the next
occurence, which then will be selected automatically. If the search
fails, there will appear a short message "Nothing found" or a few
seconds in the {\em statusbar} on the bottom of the mapeditor.

\subsubsection*{Keep the overview -- scroll a part of the map}
A very big subtree of a map e.g. a branch with hundreds of childs makes
it very hard to keep an overview over the whole map. You can hide all
the childs of a branch by {\em scrolling} it -- this function is also
often called {\em folding}. Think of the whole subtree as painted onto a
big newspaper. You can scroll the paper to a small roll, leaving just
the headline readable.

To scroll or unscroll a branch and its childs, press the
\begin{itemize}
	\item \key{Scroll} key or  \key{S}
	\item press the middle-mouse button or
	\item choose the little scroll from the toolbar.
\end{itemize}
If you select parts of a scrolled branch e.g. using the find function or
by using the arrow-keys, it will unscroll temporary. This is shown as a
scroll with a little hour glass. If the temporary unscrolled part is not
longer needed, it will be hidden again automatically. It is also
possible to unscroll all branches using "Edit\ra Unscroll all scrolled
branches".

You can also hide parts of the map while exporting it e.g. to a webpage
or a presentation, see \ref{hideexport} for details.

\subsection{Modify and move branches}
\subsubsection*{Modify the heading}
You can edit the heading by selecting the branch and then
\begin{itemize}
	\item pressing \key{Enter}
	\item double-clicking with left mouse.
\end{itemize}
Just type the new heading (or edit the old one) and press \key{Enter}.

\subsubsection*{Move a branch}
The easiest way to move a branch is to select it with left-mouse and
drag it to the destination while keeping the mouse button pressed.
Depending on the branch  it will be
\begin{itemize}
	\item moved to the destination or
	\item {\em linked} to a new {\em parent} (mapcenter or branch)
\end{itemize}
If you drag the branch over another one or over the mapcenter, you will
notice that the  link connecting it to the old parent will be changed to
lead to the  new parent which is now under your mousepointer. 
If you release the button now, the branch will be relinked.

If you release the button in the middle of nowhere, the result will
depend on the type of branch you are releasing:
\begin{itemize}
	\item A mainbranch is directly connected to the mapcenter.
		It will stay on its new position.
	\item An ordinary branch will "jump" back to its original position.	
\end{itemize}
Thus you can easily rearrange the layout of the mainbranches to avoid
overlapping of their subtrees.
There is another convenient way to move branches, especially if you want
to {\em reorder} a subtree: You can move a branch up or down in a
subtree by
\begin{itemize}
	\item pressing \key{\ua} and \key {\da}
	\item selecting Edit \ra Move branch
	\item clicking on the toolbar buttons:
		\begin{center}
			\includegraphics[width=1.5cm]{move-buttons.png}
		\end{center}	
\end{itemize}
%tipp
There is yet another way to move branches: If you press \key{Shift} or
\key{Ctrl} while moving with the mouse, the branch will be added above
or below the one the mouse pointer is over. This helps also to reorder a
map.

\subsection{The right side of your brain - colors and images}
\subsubsection*{Change color of a heading}
You can also use colors to put more information into a map, e.g. use
red, green and more colors to prioritize tasks. Again you can
\begin{itemize}
	\item use the menu and choose e.g Format \rq Set Color
	\item use the toolbar
		\begin{center}
			\includegraphics[width=3cm]{color-buttons.png}
		\end{center}	
\end{itemize}
The first button (black in the graphic above) shows the actual color.
Clicking on it let's you choose another color. You can also "pick"
another color by selecting a branch with the desired color and using the
"pick color" button. Both of the buttons showing a bucket actually put
the current color to the selected branch. While the first one just
colors the heading of the selection, the last one also colors all the
childs of the selected branch.

%tipp
A very useful function is the "copy color" using the mouse: Select the
branch which should get the new color, then press \key{Ctrl} and
simultanously click with left-mouse on another branch to copy its color
to the first one. Here the childs of the selection also will get the new
color, if you just want to color the selection itself, additionally
press \key{Shift}.

\subsubsection*{Use flags}
\vym provides various flags. You see them in the toolbar on top of the
mapeditor window. (Note: Like all toolbars you can also move them to the
left or the right side of the window or even detach them. Just grab the
very left "dotted" part of the toolbar with your left-mouse button.) 
\begin{center}
	\includegraphics[width=8cm]{default-flags.png}
\end{center}
If you have a branch selected, you can set any number of flags by
clicking them in the toolbar. The toolbar buttons change their state and
always reflect the flags set in the selected branch.

Presently \vym uses two kinds of flags: {\em System Flags} and {\em
Standard Flags}. The standard flags are those shown in the toolbar.
System flags are set by \vym to indicate e.g. that there is additional
information in a note (more on this in \ref{noteeditor}). Later versions
of \vym may have another kind of flags, which may be edited by the user.

\subsubsection*{Images}
The easiest way to add an image to a branch is by dragging it e.g. from a
webbrowser to the mapeditor while a branch is selected there.

You can also add a image to a branch by opening the context menu of the
branch choose "Add Image". A
dialog window lets you choose the image to load. 
\footnote{Supported image types are: PNG, BMP, XBM, XPM and PNM. It may
	also support JPEG, MNG and GIF, if specially configured during
	compilation (as done when \vym is part of SUSE LINUX).}
While an image is selected in the dialog, you can see a preview of the
image. It is also possible to select multiple images.	

You can position the image anywhere you want, just drag it with left
mouse. To relink it to another branch, press \key{Shift} while moving
it. To delete it, press \key{Del}. 

If you right-click onto an image, a context menu will open which let's
you first choose one of several image formats. Then a file dialog opens
to save the image. Hint: This is used to "export" the image, it will be
saved anyway in the map itself! You can also cut and
copy images, but it is not possible to add objects to an image\footnote{
	Images are regarded as "extra feature". It would make working with
	the map much more complex if e.g. images could be linked to images.}

The option \lq{\bf Use for export} \rq controls the output of exports
e.g. to HTML: If set to no, the image won't appear in the {\em text}
part of the output. This is useful for large images or if images are
used as a kind of frame e.g. the famous cloud symbol around a part of
the map. Those shouldn't appear in the middle of the text.

At the moment image support is preliminary: Images will be saved
together with all the other data of a map in the {\tt .vym}-file.
Later versions will include more functionality like resizing the images,
changing its z-value (put it into background) etc.

\subsubsection*{Frames}
A frame can be added to a branch by clicking with the
right-mouse button.  A context menu will open, where you can choose the
frame. At the moment just a rectangle resp. "No Frame" will be offered,
nevertheless you can use images as frames. Have a look at the demo map
{\tt todo.vym} as an example, where the mapcenter is a cloud. You can
use an external drawing program like {\tt gimp} to create an image,
preferable with an transparency channel, so that you can design frames
which don't use a rectangular borderline, just like the cloud.


\subsection{Background design}
The design of the background of a map and also of the links connecting
various parts of the map can be changed by
\begin{itemize}
	\item Selecting Format from the menu
	\item Right clicking onto the canvas, which will open a context menu
\end{itemize}

\subsubsection*{Background color}
The color is set (and also displayed) as "Set background color".

\subsubsection*{Link color}
Links connecting branches can be colored in one of the following ways:
\begin{itemize}
	\item use the color of the heading of the branch the links is
	\item use {\em one} color for all links. The default color is blue.
	leading to.
\end{itemize}
The latter can be set with "Set link color". Check or uncheck the "Use
color of heading for link" option to choose one of the two designs for
your map.

\subsubsection*{Link style}
\vym offers four different styles for the appearences of links:
\begin{itemize}
	\item Line
	\item Parabel
	\item Thick Line
	\item Thick Parabel
\end{itemize}
The "thick" styles only draw links starting at mapcenter thick, the rest
of the map is always painted "thin".


\subsection{Links to other documents and webpages}
\vym supports two kind of external links:
\begin{itemize}
	\item Document, which will be opened in an external webbrowser
	\item \vym map, which will be opened in \vym itself
\end{itemize}
In addition to the external links there also internal ones, leading from one
branch in a map toanother one. Those are called {\em XLinks} and are explained
in section~\ref{xlinks}.

\subsubsection*{Webbrowser}
Modern Webbrowsers like {\tt konqueror} are able to display various
types of files, both local or in the internet. To enter the URL of
any document, right-click  onto a branch or use the Edit Menu
and choose "Edit URL". Enter the path to your document (or copy and
paste it from your browser). Examples for valid paths are:
\begin{verbatim}
	http://www.insilmaril.de/vym/index.html
	file:/usr/share/doc/packages/vym/doc/vym.pdf
\end{verbatim}
If an URL was entered, a little globe will appear in the branch. By
clicking on the globe in the toolbar or the context menu an external
browser\footnote{
	The browser can be changed in the Settings Menu.}
will be started.
\begin{center}
	\includegraphics[width=0.5cm]{flag-url.png}
\end{center}
For more information on working with bookmarks and webbrowsers see
section \ref{bookmarks}.


\subsubsection*{\vym map}
To link to to another map right click on a branch or choose "Edit \ra
Enter \vym link". A file dialog opens where you can choose the map. A
branch with a link is marked with 
\begin{center}
	\includegraphics[width=0.5cm]{flag-vymlink.png}
\end{center}
Clicking this flag in the toolbar or in the context menu of a branch
will open the map in another tab (see \ref{tabs} for working with
multiple maps). To delete an existing link, just press the "Cancel"
button.

Technical note: Internally \vym uses absolute paths, to avoid opening
several tabs containing the same map. When a map is saved, this path is
converted to a relative one (e.g. {\tt /home/user/vym.map} might become
{\tt ./vym.map}. This makes it fairly easy to use multiple maps on
different computers or export them to HTML in future.

\subsection{Multiple maps} \label{tabs}
You can work on multiple maps at the same time. Each new map is opened
in another {\em tab}. The available tabs are shown just above the
mapeditor. You can use the normal cut/copy/paste functions to
copy data from one map to another.

%todo

%TODO
%\subsubsection{Menus}
%\subsubsection{Keyboard shortcuts}

% Settings
% Images
% Copy & Paste
% Working with tabs (multiple maps)
% Exporting
% Scrolling

\section{Noteeditor} \label {noteeditor}
If you want to save more text in a branch e.g. a complete email, a
cooking recipe, or the whole source code of a software project, you can
use the noteeditor. 
\begin{center}
	\includegraphics[width=8cm]{noteeditor.png}
\end{center}
This editor displays text associated to a branch selected in the
mapeditor. To visualize that there maybe is no text yet, the noteeditor
shows different background colors depending on its state:

\subsection{States}
Before you can type or paste text into it, you have
to select a branch in the mapeditor. Note that the background color
of the noteeditor indicates its state:
\begin{itemize}
	\item black: no branch selected
	\item grey: no text entered yet
	\item white: text is already available
\end{itemize}	
To show you in the mapeditor itself that there is a note with more
information for a particular branch, a little note flag will appear next
to the heading of the branch. See the lower branch on the right side:
\begin{center}
	\includegraphics[width=8cm]{branches-flags.png}
\end{center}

\subsection{Import and export notes}
The note is always saved automatically within the \vym file itself.
Nevertheless sometimes it is nice to import a note from an external file
or write it. Use "File\ra~Import" and "File\ra~Export" to do so. 

\subsection{Edit and print note}
Editing works like in any simple texteditor, including undo and redo
functions. You can delete the complete note by clicking the
trashcan. Only the note itself is printed by clicking the printer icon.

When pasting into the editor using the X11 copy\&paste mechanism, the
editor will create a paragraph for each new line. Usually this is not
wanted, so there you can convert all paragraphs into linebreaks by using
Edit~\ra~Remove~Paragraphs or \key{ALT-X}.

\subsection{RichText: Colors, paragraphs and formatted text}
\vym supports formatted text (QT Rich Text) in the noteeditor since
version 1.4.7.  Colors and text attributes (e.g. italic, bold) can be
set with the buttons above the text.  The text itself is divided in
paragraphs. For each paragraph the format can be set (e.g. centered,
right). A paragraph is ended when a \key{Return} is entered. If you just
want to begin a new line, press \key{CTRL-Return}.

\subsection{Fonts and how to quickly switch them}
The noteeditor is ment to be used for simple notes, not really as full
featured text editor. Because of many requests \vym supports now
formatted text in the noteeditor\footnote{
	\vym uses the QRichtText format, which is basically a subset of the
	formatting provided in HTML.}
Two default fonts are supported which can be set in the Settings menu.
One is a fixed width font, the other has variable width. The fixed font
is usually used for emails, source code etc.\ while the variable font is
used for simple notes, where one doesn't need fixed character widths.
Both fonts can easily switched using the following symbol from the
toolbar:
\begin{center}
	\includegraphics[width=0.5cm]{formatfixedfont.png}
\end{center}
In the Settings menu both fonts can be set and also which font should be
used for default. 

Additionally to the default fonts any font installed on your system can
be used. Please note, that the chosen font also will be used for HTML
exports, so you should only use fonts which are available generally.

\subsection{Find text}
The noteeditor itself has no Find function, use Find in the mapeditor,
which will also search all notes (see \ref{findwindow}).

\subsection{Paste text into note editor}
Often you will paste text into the editor from another application e.g.
an email. Normally \vym will generate a new paragraph for each new line.
This usually is not what you want, so you can choose from the menu

\subsection{Advanced actions}
\subsubsection*{Edit \ra Convert subsubsections:}
This turns subsubsections in selected text (or all text, if nothing is
selected) into linebreaks. This is especially useful for snippets of
source code.

\subsubsection*{Edit \ra Join Lines:}
Tries to format text, so that empty lines are used to delimit
paragraphs. This is done for selected text (or all text, if nothing is
selected). Especially useful for text like emails, meeting minutes etc.

\section{Hello world}
This section is about how \vym can interact with other applications.
Many applications meanwhile can read and write their data using XML, the
eXtensible Markup Language. \vym also uses XML to save its maps, see
\ref{fileformat} for a more detailed description. 

So if your an application understands XML, chances are good that someone
could write import/export filters for \vym. Volunteers are always
welcome ;-)

\subsection{Import} \label{import}

\subsubsection*{KDE Bookmarks}
The integrated bookmark editor in KDE is somewhat limited, so why not
use \vym to maintain the bookmark mess? To create a new map containing
your current KDE bookmarks just choose
\begin{itemize}
	\item File \ra Import\ra KDE Bookmarks
\end{itemize}

\subsubsection*{Mind Manager}
\vym has currently a very basic import filter to convert maps created by
{\em Mind Manager}\footnote{Mind Manager is a professional software by
Mindjet. Both names are registered trademarks by Mindjet. For more
information see their website at
\href{http://mindjet.de}{http://mindjet.de}} into \vym maps. Notes and
pictures are not converted at the moment. You can import files with
\begin{itemize}
	\item File \ra Import\ra Mind Manager
\end{itemize}


\subsubsection*{Directory structure}
\vym can read a directory structure. This is mainly for
testing \vym e.g. to easily create huge maps used for benchmarks (yes,
there is still room to optimize \vym ;-)




\subsection{Export}  \label{export}
\label{hideexport}
Often you don't want to export the whole map, but just parts of it. For
example you may have additional info you want to talk about in a
presentation, while those parts should not be visible to the audience.
To achieve this you can "hide" parts of the map during exports by
setting the "hide in export" flag.
\begin{center}
	\includegraphics[width=0.5cm]{flag-hideexport.png}
\end{center}
You can toggle this flag in the toolbar or by pressing \key{H}.
Note that there is a global option in the settings menu to toggle the
use of this flag. By default the flag is enabled.

\subsubsection*{Open Office}
Open Office beginning with version~2 uses the so called "Open Office
Document Format", which can be written by \vym. The options are
currently limited, but it possible to export presentations which can be
opened in Open Office Impress. By selecting
\begin{itemize}
	\item File \ra Export\ra Open Office
\end{itemize}
you get a file dialogue where you can choose the output file and the
file type:
\begin{center}
	\includegraphics[width=12cm]{export-oo.png}
\end{center}
The file types represent various templates, which can be created with
some manual work from an existing Open Office document. The structure of
\vym map is then inserted into a template. 
There are some limitations at the moment:
\begin{itemize}
	\item \vym can't take care of page lengths, so you have to check and
	probably reedit in Open Office to avoid text running over the end of
	a page
	\item Images and flags are not used at the moment
	\item Notes are just written as plain text, without RichText
\end{itemize}
Some of the templates make use of {\em sections} e.g. insert the
headings of mainbranches as chapters for sections into the presentation.

\subsubsection*{Image}
\vym supports all image formats which are natively supported by the
QT~toolkit:
BMP, JPEG, PBM, PGM, PNG, PPN, XPM, and XBM.
For use in websites and for sending images by email PNG is a good
recommodation regarding quality and size of the image. \vym uses QTs
default options for compressing the images.

\subsubsection*{ASCII}
Exporting an image as text is somewhat experimental at the moment. Later
this will probably done using stylesheets. So the output may change in
future versions of \vym.

\subsubsection*{\LaTeX}
\vym can generate an input file for \LaTeX. Currently this is considered
as experimental, there are no options (yet). 
By selecting
\begin{itemize}
	\item File \ra Export\ra \LaTeX 
\end{itemize}
you will be asked in a file dialog for the name of the output file. This
file should be included in a \LaTeX document using command  
\begin{verbatim}
	\include{inputfile.tex}
\end{verbatim}

\subsubsection*{KDE Bookmarks}
\vym will overwrite the KDE bookmarks file and then try to notify
running konquerors via DCOP of the changed file. \vym does not create a
backup!
\begin{itemize}
	\item File \ra Export \ra KDE Bookmarks
\end{itemize}


\subsubsection*{XHTML (Webpages)}

This is the format you want to use to create a webpage. For an example
have a look at the \vym homepage: 
\href{http://www.InSilmaril.de/vym}{www.InSilmaril.de/vym}

Some explanation how this works: 
Before a map is exported as XHTML, it will be first written as XML into a
directory (see \ref{xmlexport}). Then the external program {\tt
xsltproc}\footnote{On SUSE Linux {\tt xsltproc} is installed by
default.}
will be called to process the XML file and generate HTML code.
A dialog allows to set various options:
\begin{itemize}
	\item {\bf Include image:} If set, \vym will creat an image map at
	the top of the HTML output. Clicking on a branch in the map will
	jump to the corresponding section in the output.

	\item {\bf Colored headings:}
	If set to yes, \vym will color the headings in the text part  with the
	same colors like in the map.
	\item {\bf Show Warnings:}
	If set to yes, \vym will ask before overwriting data.
	\item {\bf Show output:}
	This is useful mainly for debugging. It will show how the processing of
	the XML file works by calling the external {\tt xsltproc}.
\end{itemize}
Additionally the paths to the CSS and XSL stylesheets can be set. By
default on SUSE~Linux they will be in {\tt /usr/share/vym/styles}.


\subsubsection*{XML} \label{xmlexport}
The map is written into a directory both as an image and as XML. The
directory is set in a file dialog. If the directory is not empty, you
will be questioned if you risk to overwrite its contents.

It is possible to export different maps into the same directory. Each
file generated will have the map's name as prefix, e.g. {\tt todo.vym}
becomes {\tt todo.xml}, {\tt todo.png}, {\tt todo-image-1.png} and so
on. This is useful if e.g. for a website several combined maps have to
be stored in the same directory.

\subsubsection*{Export a part of a map}
Select a branch you want to export together with its childs, then open
the context menu and choose {\em Save Selection}. This will create a
file with the postfix {\tt .vyp}, which is an abbreviation for \lq vym
part\rq.


\section{Advanced Editing}

\subsection{How to deal with Bookmarks} \label{bookmarks}
\subsubsection*{Open new tabs instead of new windows}
If you use konqueror as browser, \vym will remember the konqueror which
was opened first by \vym. You can also press \key{Ctrl} and click to
open the link in a new tab then.

\vym can also open a new tab in Mozilla or Firefox using the remote
command\footnote{\href{http://www.mozilla.org/unix/remote.html}{http://www.mozilla.org/unix/remote.html}}
of these.

\subsubsection*{Drag and Drop}
If you want to keep bookmarks in a map, select a branch where you want
to add the bookmark, then simply drag the URL from your browser to the
map. Also you could use an existing heading as URL: Right click onto the
branch and select "Use heading for URL".


\subsubsection*{Directly access bookmark lists of a browser}
Please see the sections \ref{import} and \ref{export} about
Import and Export filters.

\subsubsection*{Special URLs}
\vym can turn an existing heading of a branch into an URL. Currently
this works for Bugentries in the Novell Bugtracking system: Open the
context menu of a branch (usually by right-clicking it) and select
\begin{itemize}
	\item Create URL to Bugzilla
\end{itemize}
The URL will be build from the number in the heading.

\subsection{Including images into a branch} 
The default setting of an image is to float "freely". They can be
positioned everywhere, but they might end up in the same place as other
parts of the map.

The solution is to include them "into" a branch. This can be done via
the context menu of their parent branch:
\begin{itemize}
	\item Include images horizontally
	\item Include images vertically
\end{itemize}
The image ist still positioned relatively to its parent branch, but the
heading and border of the branch adapt to the floating image, see below: 
\begin{center}
	\includegraphics[width=11cm]{includeImages.png}
\end{center}

\subsection{Modifier Modes} 
Modifiers are for example the \key{Shift}- or the \key{Alt}-keys. When
pressed while doing actions with the mouse, they will cause \vym to use
a "modified" action. E.g. you can move branches with mouse. If
\key{Ctrl} or \key{Alt}is pressed while releasing the branch, it will be
added above/below the target, not as child of the target.

Without a modifier pressed, the first click on a branch just selects
it. For the behaviour of the \key{Ctrl} modifier there are several
options, which can be set from the modifier toolbar:
\begin{center}
	\includegraphics[width=3cm]{modmodes.png}
\end{center}
The default  is to copy the color from the clicked branch to the already
selected branch. In the toolbar shown above the default modifier is
selected, namely to copy the color of a branch. The second modifier
let's you easily copy a whole branch with a single click. The third
modifier lets you create {\em xLinks}, which will be explained in the
next section.

\subsection{Hide links of unselected objects}
Sometimes it would be useful to position a branch freely, just like a
mainbranch or an image. Though this is not possible (yet) for all
branches, you can use a mainbranch and hide its connecting link to the
mapcenter. This can be used e.g. for legends or a collection of vymLinks
pointing to other maps:
\begin{center}
	\includegraphics[width=9cm]{hiddenlink.png}
\end{center}


\subsection{XLinks} \label{xlinks}
So far all the data in the \vym map has been treelike. Using xLinks you
can link one branch to any other, just like attaching a rope between two
branches in a real tree. This is especially useful in complex maps,
where you want to have crossreferences which don't fit on the same
visible area, which fits on your screen. The following example, which is
part of the \vym package, still fits on one screen, but shows how data
can be crosslinked. In the graphics there is a link from a task (prepare
a presentation) to general information:
\begin{center}
	\includegraphics[width=12cm]{xlink.png}
\end{center}
Note that a xLink which points to a branch that is not visible (because
it is scrolled), is just show as a little horizontal arrow. In the
screenshot above have a look at the \lq Tuesday\rq\ branch.

\subsubsection*{Create a xLink}
Choose the link mode from the modifier toolbar (by clicking or pressing
\key{L}). Select the branch, where the xLink should start. Press the
modifier key \key{Ctrl} and simultanously click on the branch where the
link should end. (The link is already drawn before you release the mouse
key). If you release the mouse over a branch the xLink becomes
permanent.

\subsubsection*{Modify or delete a xLink}
Open the context menu of a branch and select \lq Edit xLink\rq. A
submenu contains all the xLinks of the branch (if there are any). They
are named like the branches, where they end. Choose one and
the xLink dialogue opens, where you can set color, width and also delete
the xLink.

\subsubsection*{Follow a xLink}
In a complext \vym map it sometimes comes handy to jump to the other end
of a xLink. You can do this by opening the context menu of the branch
and clicking on \lq Goto xLink\rq and selecting the xLink you want to
follow.



\subsection{Adding and removing branches}
The context menu of a branch shows some more ways to add and delete data
e.g. you can delete a branch while keeping its childs. The childs become
linked to the parent of the previously removed branch.
Similar branches can be inserted into existing maps. For keyboard
shortcuts also have a look at the context menu.

\subsection{Adding a whole map or a part of a map}
Select a branch where you want to add a previously saved map ({\tt .vym})or a part
of a map ({\tt .vyp}) , then open
the context menu and choose {\em Add \ra Import}. For the import you can
choose between {\em Import Add} and {\em Import Replace}: The imported
data will be added after the selection resp. replace the selection.


\section{\vym on Mac OS X}
\subsection{Overview}
Basically there are two ways to run \vym on Macs:
\subsubsection*{QT Mac Edition:}
	\vym here provides the well known Mac look and feel.  \vym is
	available as zipped Mac OS X application. It has been compiled and
	tested in Mac~OS~10.3, but should also work on Tiger. It is using
	the Mac version of Trolltechs QT library.  
\subsubsection*{X11}
	\vym can also be run using the Linux version, but then menus and
	handling will also be those of the Linux version e.g. The menu bar
	will look different. 

\subsection	{Contextmenu and special keys}
Most Macs unfortunatly just have a single mouse button. In order to show
the context menu which usually would be opened with the right mouse
button, you can click while pressing the \key{kommand}-key.

Especially on Laptops some of the keys usually used on PC keyboards seem
to be missing. The QT-Mac Edition of \vym has its own keyboard
shortcuts. To find the shortcuts just have a look at all the menu
entries, the shortcut is visible next to an entry. Toolbar buttons also
may have shortcuts, just position the mouse pointer over a button and
wait for the little help window to appear. 

\subsection {Viewing external links}
\vym on Mac uses the system call {\tt /usr/bin/open} to view links.
Mac~OS determines automatically if the link is a pdf or www page and
opens the right browser.


\begin{appendix}

\section{Starting \vym}
\subsection{Path to ressources}
\vym will try to find its ressources (images, stylesheets, filters,
etc.) in the following places:
\begin{enumerate}
	\item Path given by the environment variable {\tt VYMHOME}.
	\item If called with the local option (see \ref{options} below),
	      \vym will look for its data in the current directory.
	\item {\tt /usr/share/vym}
	\item {\tt /usr/local/share/vym}
\end{enumerate}

\subsection{Command line options} \label{options}
\vym has the following options:
\begin{center}
\begin{tabular}{ccp{8cm}}\\ 
\bf Option	& \bf Comment & \bf Description \\ \hline
v & version & Show version ov \vym\\
l & local	& Use local paths to stylesheets, translations, icons, 
              etc. instead of system paths. Useful for testing\\
h & help	& Show help\\
q & quit	& Quit immediatly after startup. Useful for benchmarks.\\
\end{tabular}
\end{center}
You can also give several filenames at the commandline to let \vym open
several maps at once.
 
\section{Contributing to \vym}
So far I'd say I have written 98\% of the code on my own. No surprise,
that \vym exactly fits my own needs. Nevertheless I would like to
encourage all users of  \vym to contribute. Maybe not only with feature
requests, but also with code, new import/export filters, translations
etc. In this appendix I'll try to show how easy it is to expand the
things you can do already with \vym. I really look forward to hear from
you!

\subsection{Getting help}

\subsubsection*{Frequently asked questions}
Please refer to the FAQ available on the \vym website:
\begin{center}
\href{http://www.InSilmaril.de/vym/faq.html}{http://www.InSilmaril.de/vym/faq.html}
\end{center}

\subsubsection*{Mailinglists}
There are two mailinglists: {\tt vym-forum} is the \vym users forum to
discuss various questions, while {\tt vym-devel} is intended for people
interested in contributing to \vym. You can view the archives and
subscribe at
\begin{center}
\href{https://sourceforge.net/mail/?group_id=127802}{https://sourceforge.net/mail/?group\_id=127802}
\end{center}

\subsubsection*{Contacting the author}\label{author}
Especially for support questions please try the mailinglists first. If
everything else fails you can contact the Uwe Drechsel at
\begin{center}
\href{mailto:vym@InSilmaril.de}{vym@InSilmaril.de}
\end{center}



\subsection{How to report bugs}
Though Sourceforge has its own bugreporting system, I'd rather prefer if
you contact me directly (see \ref{author}) or even better: You can file
a bugreport in Bugzilla, the bugtracking system of openSUSE:
\begin{center}
\href{http://en.opensuse.org/Submit_a_bug}{http://en.opensuse.org/Submit\_a\_bug}
\end{center}
I build \vym regulary for openSUSE, so you may report it against a
recent version there, even if you  use another Operating System.
Please don't forget to tell 
\begin{itemize}
	\item the exact steps needed to reproduce the bug
	\item the version and build date of \vym (see the Help \ra About
	\vym)
	\item hardware and Operating System
\end{itemize}

\subsection{Compiling from the sources}
\subsubsection{Getting the sources} \label{getsources}
You find the latest version of \vym at the project site:
\begin{center}
\href{https://sourceforge.net/projects/vym/}{https://sourceforge.net/projects/vym/}
\end{center}
There you can check them out of the source repository (CVS):\\

\begin{verbatim}
cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/vym checkout code
\end{verbatim}

\subsubsection{The Qt toolkit}
Qt is C++ toolkit for multiplatform GUI and application development. It
provides single-source portability across MS~Windows, Mac~OS~X, Linux
ans all major commercial Unix variants. Qt is also available for
embedded devices. Qt is a Trolltech product. For more information see 
\begin{center}
\href{http://www.trolltech.com/qt/}{www.trolltech.com/qt} 
\end{center}


\subsubsection{Compiling \vym }
Make sure you have installed your Qt environment properly, see the Qt
documentation for details. You need to have the Qt command {\tt qmake}
in your {\tt PATH}-environment, then run
\begin{verbatim}
qmake
make  
make install
\end{verbatim}
The last command {\tt make install} needs root-permissions. Of course it
may be omitted, if you just want to test \vym.

%\subsubsection*{Compiling \vym on Macs}
%TODO

\subsection{\vym file format} \label{fileformat}
\vym maps usually have the postfix "{\tt .vym}" and represent a
compressed archive of data. If you want to have a
closer look into the data structure map called "mapname.vym", 
just uncompress the map manually using
\begin{verbatim}
	unzip mapname.vym
\end{verbatim}
This will create directories named {\tt images} and {\tt flags} in your
current directory and also the map itself, usually named {\tt
mapname.xml}.
The XML structure of \vym is pretty self explaining, just have a look at
{\tt mapname.xml}.

This XML file can be loaded directly into \vym, it does not have to be
compressed. If you want to compress all the data yourself, use
\begin{verbatim}
	zip -r mapname.vym .
\end{verbatim}
to compress all data in your current directory.

\subsection{New features}
There are lots of features which might find their way into \vym.
Together with \vym you should have received a directory with several
maps e.g. on SUSE~LINUX this is
\begin{center}
	{\tt /usr/share/doc/packages/vym/demos}
\end{center}
where you find the map {\tt todo.vym}. It lists quite a lot of things to
be done in future. If you have more ideas, contact the development team
at
{\tt vym-devel@lists.sourceforge.net}.


\subsection{New languages support}
In order to add a new language to \vym you need 
the sources (see \ref{getsources}) and
an installation of Trolltechs QT. A part of QT are the development
tools, from those tools especially the translation tool "Linguist" is
needed. 

In some Linux distributions the development tools are in an extra package, e.g. on SUSE LINUX you should have installed:
\begin{verbatim}
    qt3-devel.rpm
    qt3-devel-doc.rpm
    qt3-devel-tools.rpm
    qt3-man.rpm
\end{verbatim}
If you don't have QT in your system, you can get it from 
	\href{http://www.trolltech.com}{http://www.trolltech.com} Once you
	are able to compile vym yourself, you can translate the text in vym
	itself by performing the following steps:
\begin{itemize}
	\item Let's assume now your encoding is "NEW" instead of for example
	"de" for german or "en" for english
	
	\item Copy the file {\tt lang/vym\_en.ts} to l{\tt ang/vym\_NEW.ts} (The code
	itself contains the english version.)
		
	\item Add {\tt lang/vym\_NEW.ts} to the TRANSLATIONS section of vym.pro

	\item Run Linguist on {\tt vym\_NEW.ts} and do the translation

	\item Run {\tt lrelease} to create {\tt vym\_NEW.qm}

	\item Do a make install to install the new vym and check your translation
\end{itemize}

If you feel brave, you can also translate the manual. It is written in
LaTeX, you just have to change the file tex/vym.tex. (Linguist and QT
are not needed, but it is useful to know how to work with LaTeX and esp.
pdflatex to create the PDF.) 

Please mail me every translation you have done. I can also give you a
developer access to the project, if you want to provide translations
regulary.  

\subsection{New export/import filters}
\vym supports various kinds of filters. Data can be written directly,
inserted into templates or it can be written as XML data and then
processed by XSL transformations. 

Most of the import/export functionality is available in the classes
ImportBase and ExportBase and subclasses. All of them can be found in
{\tt imports.h} and {\tt exports.h}.

\subsubsection*{Direct import/export}
An example for a direct export is the XML export. This method touches
the implementation of nearly every object of \vym, so whenever possible
you should better use a XSL transformation instead.

If you still want to know how it is done, start looking at 
{\tt MapEditor::saveToDir} in {\tt mapeditor.cpp}.

\subsubsection*{Templates}
Templates have been introduced to export to opendoc format used e.g. by
Open~Office. While I read the spec ($>$ 500 pages) about the format\footnote{
\href{http://www.oasis-open.org/}{http://www.oasis-open.org/}}\ 
I had the feeling that I did not want to write the export from scratch. 
It would be too complex to adapt the styles to your own wishes, e.g. the
layout.

Instead I analyzed existing Open~Office documents. I found out that
there are lots of redundant bits of information in a standard
presentation, for example each list item is contained in its own list.
In the end I came up with the default presentation style, which still
could be simplified, just in case you have free time\ldots

The existing templates are still work in progress, before you spent too
much time developing your own style, please contact me.  Basically the
following steps are needed to build your own style:
\begin{enumerate}
	\item Create an example in Open Office. Use a title, authors name,
	page heading etc.\ which you can easily grep for in the output file.
	
	\item Unzip  the Open Office document into a directory.

	\item The main file is called {\tt content.xml}. All data is in one
	single line. You can split the XML tags using the script {\tt
	scripts/niceXML}, which is part of the \vym distribution.

	\item Copy the output of {\tt niceXML} to {\tt
	content-template.xml}.

	\item Looking closer you will find lots of unused definitions, for
	example of styles. You can delete or simply ignore them.

	\item Try to find your title, authors name. \vym will replace the
	following strings while exporting:
	\begin{center}
	\begin{tabular}{lp{4cm}}
		{\tt <!-- INSERT TITLE -->}		& title of map \\
		{\tt <!-- INSERT AUTHOR-->	}	& author \\
		{\tt <!-- INSERT COMMENT -->}	& comment \\
		{\tt <!-- INSERT PAGES-->}		& content of map \\
	\end{tabular}
	\end{center}
	The content itself is generated in a similar way by inserting lists
	into {\tt page-template}. Here the following substitutions are made:
	\begin{center}
	\begin{tabular}{lp{7cm}}
		{\tt <!-- INSERT PAGE HEADING-->}		& heading of a page
		(mainbranch or child of mainbranch, depending on the use of
		sections) \\
		{\tt <!-- INSERT LIST -->	}	& all childs of the branch above \\
	\end{tabular}
	\end{center}
\end{enumerate}
Currently images are exported and notes just will appear as text
without formatting and colors.




\subsubsection*{XSL Transformation}
\vym uses XSL transformations while exporting (e.g. XHTML) and importing
data (e.g. KDE bookmarks). There is a little code needed to provide the
GUI, the rest is done using the {\tt .xsl} stylesheet and calling the
{\tt xsltproc} processor, which is part of libxslt, the XSLT
C  library  for  GNOME. 

\end{appendix}
\end{document}

%TODO
%\subsubsection{Menus}
%\subsubsection{Keyboard shortcuts}
%Where does vym save its settings? -> ~/.qt/vymrc


% INDEX
% mapeditor
% noteditor
% branch
% mapcenter
% heading
% flag
% orientation 
% zoom
% orientation
% Toolbar
% Zoom
% Find
% statusbar
% link
% mainbranch
% subtree
% reorder
% scroll
% fold
% vymlink
% xlink
% modMode
% context menu
% Mac OS X



\end{document}
