\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{VYM \\ -- \\View Your Mind}

\author{\textcopyright Uwe Drechsel  }

\maketitle

\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 paper or a flip chart and help to

structure your thoughs. While a tree like structure like above can be

drawn by hand or any drawing software \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.

\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 critize

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}

\subsection{Concept of \vym}

%TODO may add a general introduction here...

\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}

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 \lq

thumb-up\rq flag is set, then the \lq thumb down\rq is unset and vice

versa. You can change this default behaviour in the settings menu.

\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*{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".

\subsection{Modify and move branches}

\subsubsection*{Modify the heading of a branch}

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.	

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{Link to other documents}

Presently \vym supports two kind of 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}

\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}

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*{\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. 

\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{Fonts}

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{Colors 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{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}

\vym can export its maps in various formats and can import data from

outside (though import is still limited at the moment).

Also parts of a map can be exported.

\subsection{Export}

The format in which the map will be exported can be chosen with

\begin{itemize}

	\item File \ra Export \ra {\em format}

\end{itemize}

\vym offers both HTML and ASCII export.

\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*{HTML}

Before a map is exported as HTML, 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 script then will transform the XML

%version. 

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}.

%\paragraph{WIKI style:} This is very useful for easy design of webpages.

%Here is a short overview:

%\begin{verbatim}

%Lines:

%	+ Big headlines start with the '+' character.

%	- Small headlines start with the '-' character.

%	  Normal text doesn't have any starting notation.

%	! Notes start with an exclamation.

%	. Indented text starts with a dot.

%	? Questions start with a question-mark, and

%	= Answers starts with the equal-sign.

%	* Points for a item-list

%	# clues

%	

%Links:

%	use '{...}' or '{(vym homepage) http://www.insilmaril.de/vym/}'

%	for external links.

%	

%Markup:

%	|This is bold| text, while 

%	|/this text is italic|, 

%	|*this is pre-formatted|, and 

%	|!this is a note|

%\end{verbatim}

%

%\paragraph{Show output:} This is used for debugging. \vym uses an

%the external script {\tt vym2html.sh} to preprocess the XML-data. Then

%\vym calls {\tt xsltproc} to generate the HTML page by using various

%{\tt .xsl} stylesheets and {\tt wireframe.css}. If you run into problems

%here, changing paths in {\tt $\sim$/.qt/vymrc} might help.

\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.

\subsection{Import} 

Many applications meanwhile can export their data using XML. \vym also

uses XML to save its maps, see \ref{fileformat} for a more detailed

description.

%TODO

%Import of vym maps somewhere (context menu)

%Import of "foreign" formats

volunteers to write import filters are welcome.

Also parts of a vym map ({\tt .vyp}) can be imported.

\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{\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, just uncompress the map manually

using

\begin{verbatim}

	unzip vymfile.vym

\end{verbatim}

A directory named {\tt vymfile} will be created containing further

directories both for {\tt images} and {\tt flags}. In the {\tt vymfile}

directory you will find the map itself, usually named {\tt vymfile.xml}.

This 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}

	cd vymfile

	zip -r vymfile.vym .

\end{verbatim}

\subsubsection*{Importing a part of a map}

Select a branch where you want to add a previously save 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{Advanced Editing}

\vym offers a few shortcuts to let you work more quickly and literally

to connect any branches directly.  

\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{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{Ctr} 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 links}

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.

\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.

\subsection{Compiling \vym on Macs}

Please refer to the documentation available on the internet:

\begin{center}

\href{http://www.InSilmaril.de/vym/faq.html}{http://www.InSilmaril.de/vym/faq.html}

\end{center}

\end{document}

\section{History of \vym}

\subsection{Future}

There are lots of features which might find their way into \vym.

Together with \vym you should have received a directory with example

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 author at

{\tt vym@insilmaril.de}.

\subsection{Past}

\input{vym.changelog}

\begin{center}

\begin{longtable}{|lcp{8cm}l|} \hline

Version	&	&	Comment								& Date	\\ \hline \hline \endhead

	\hline \endfoot

1.6.8	& - &	Dramatic speedup in some operations 

				(e.g. move branch up/down) due to extended 

				undo engine							& 2005-06-07 \\ 

1.6.7	& - &	Changed default pdf-reader for Mac OSX & 2005-05-27 \\ 

		& - &	Bugfix: xLinks stopped working in 1.6.6			&\\

		& - &	Bugfix: drawing error when using modModeCopy    &\\

		& - &	Bugfix: replaced lrint by qRound for BSD ports	&\\

1.6.6	& -	&	Exclusive standard flags			& 2005-05-23 \\

1.6.5	& -	&	removing a branch and keeping its childs	& 2005-05-19 \\

        & -	&	removing childs of a branch			& \\

        & -	&	insert branch and make selection its child& \\

        & -	&	restructured branch context menu	

				in a basic version (straight line)	& 2005-04-15\\

        & -	&	New shortcuts  for use on Mac OS X	& \\

        & -	&	Importing directories generates vymlinks now & \\

        & -	&	Bugfix: Changing linkstyle now automatically redraws all

				links again& \\

        & -	&	Bugfix: Paste icon is disabled if clipboard is empty &\\

1.6.4	& -	&	xLinks (arbitrary connection between 2 branches) works

				in a basic version (straight line)	& 2005-04-15\\

1.6.3	& -	&	Bugfix: Saving of selection to a vym part (.vyp)	&2005-03-30\\

		& - &	Bugfix: Closing the noteeditor by closing its window now

				also toggles the responding toolbar button. &\\

1.6.2	& -	&	Introduced Modifier modes: color, link, copy &2005-03-24\\

      & -	&	Linking branches is basically possible, though it can't

				be edited/saved yet &\\

1.6.1	& -	&	Optimized moving of branches: much faster especially 

				with huge subtrees					&2005-01-30\\

		& -	&	Bugfix: Segfault when loading vym part &\\

		& -	&	Bugfix: ugly unitialized lines, when 

				temporary drawn link was moved from a 

				temporary parent back to canvas		& \\ 

1.6.0 	& -	&	Added saving of xhtml settings in map& 2004-12-14 \\ 

1.5.2 	& -	&	Added Import of maps with two modes: 

				add/replace							& 2004-12-13 \\ 

		& - &	Added export of part of maps		& \\

		& - &	Added joining of paragraphs in text editor		& \\

		& - &	Optimized undo: Only relevant parts are saved, which

				dramatically improves e.g. moving branches up/down 

				in most maps & \\

		& -	&	Bugfix: QTextEdit generates invalid XML code, which

				could lead to a parse error, if font name contains a \& &  \\ 

		& -	&	Bugfix: Wrong order of mainbranches in Export	&  \\ 

		& -	&	Bugfix: zip archive was not deleted before save, which

				could lead to much bigger files, e.g. 

				when working on older \vym maps or deleted images&  \\ 

		& -	&	Bugfix: Printing in Texteditor      &  \\ 

		& -	&	Bugfix: Wrong URLs in xhtml output				&  \\

      	& -	&	Bugfix: Segfault fixed at Cursor left/right in empty map&  \\

1.5.1 	& -	&	More options in xhtml export: external scripts 	& 2004-10-01 \\

1.5.0 	& -	&	Public release of all changes since 1.4.1      	& 2004-09-26 \\

      	& -	&	New function to replace paragraphs in note editor

				by linebreaks, this makes pasted text much nicer& \\

      	& -	&	New option to toggle exporting of of floatimages& \\

      	& -	&	z-plane of floatimages can be set (manually only)& \\

		& - &	Bugfix: Wrong ordering of branches, if mainbranch is

				exactly left of center& \\

1.4.7 	& -	&	New Export to XHTML by Thomas Schraitle.	& 2004-09-24 \\

		& - &	Bugfix: vymLink&	\\

		& - &	Bugfix: spaces and dots in filenames	& \\

		& - &	Bugfix: Error message if xsltproc is not installed& \\

1.4.6 	& -	&	New file format: notes are saved as part of the .xml file

			& 2004-09-15	\\

		& - &	Note Editor supports Rich Text now.&\\

		& - &	Parser now also nows {\tt standardflag} (all letters

				lowercase)&\\

1.4.5 	& -	&	Correct handling of font size in Heading			& 2004-08-23	\\

1.4.4 	& -	&	Selecting with cursor now works between subtrees	& 2004-07-29	\\

		& - &	Bugfix: vymLink was set to temporary dir in 1.4.3	& \\

		& - &	Bugfix: & \\

1.4.3 	& -	&	Optimisation: Reduced canvas objects by only

				creating objects for used flags		& 2004-07-19 \\ 

		& - &	Better visualization of moving branch above/below target&\\		

		& - &	Find Window informs with dialog, if the search failed&\\

		& - &	System Flags are clickable now		&\\

		& - &	Reworked CSS and XST stylsheets (comments, indent, browser

				compatibility)						&\\

		& - &	vymLinks are shown in statusbar		&\\

		& - &	current directory is save			&\\

		& - &	Rewritten load/save to improve multimap handling and

				unzipped files&\\

		& - &	Bugfix: vymLinks don't get deleted 

				when Cancel is pressed				&\\		

      	& -	&	Bugfix: Fixed a bunch of bugs in XSL for HTML export&            \\ 

      	& -	&	Bugfix: More toolbar buttons disabled, if action not

				possible&            \\ 

		& - &	Bugfix: Renaming .vymfile now works&\\		

		& - &	Bugfix: mapChanged set when toggling flags&\\		

		& - &	Bugfix: CTRL-N was used twice		&\\

		& - &	Bugfix: Del didn't work on floatimage &\\

1.4.2 	& -	&	Bugfix: Float image could not be deleted& \\ 

1.4.1 	& -	&	Bugfix: Color of branch not saved	& 2004-05-25 \\ 

      	& -	&	Bugfix: wrong path at HTML export	&            \\ 

		& -	&	Bugfix: map is not save with special characters in path&  \\ 

1.4.0 	& -	&	Ask for confirmation before opening 

				a map in multiple editors			& 2004-05-17 \\

		& - &	Save state of note editor (visible/minimized)& \\

		& - &	Export to HTML						& \\

		& - &	Author and Comment is saved in map	& \\

		& - &	Stats are shown in Edit MapInfo		& \\

		& - &	Changes for OS X port (QCursor, QContextMenuEvent)	& \\

		& - &	Bugfix: Fonts from note editor are save now			&\\

		& - &	Bugfix: invisible image when parent is scrolled		&\\

		& - &	Bugfix: Segfault pressing "enter" for floatimage	&\\

		& - &	Bugfix: Images can't be outside of exported area

				anymore.& \\

		& - &	Bugfix: Filenames with blanks		& \\

		& - &	Bugfix: Old maplink is shown when editing maplink& \\

		& - &	Bugfix: always show cursor while editing heading & \\

1.3.5 	& -	&	Export map to dir					& 2004-04-16 \\

		& - &	Export to any of QTs image formats	& \\

		& - &	Also right side of selection is always visible now.& \\

1.3.4 	& -	&	Load last maps in file menu         & 2004-04-07 \\

		& - &	save last image path for loading	& \\

		& - &	Also export standard flags to dir.	& \\

1.3.3 	& -	&	Enabled <br> in headings as manual linebreak	& 2004-03-26 \\

		& -	&	Heading can be copied to URL		&\\

		& -	&	Bugfix: GIFs are automatically converted to PNG now&\\

1.3.2 	& -	&	Add and move branches above/below selection, Texteditor copy all,& 2004-03-26 \\

1.3.1 	& -	&	Export to directory, changed naming in .vym& 2004-03-25 \\

1.3.0 	& -	&	Bugfix: Check if map can be saved at all& 2004-03-23 \\

1.2.12	& -	&	Select image format before saving image	& 2004-03-22 \\

1.2.11	& -	&	Selecting mainbranches by up/down	& 2004-03-18 \\

		& -	&	Export ASCII (experimental)			&			\\