tex/vym.tex
author insilmaril
Mon, 30 Jul 2007 09:47:29 +0000
changeset 578 610cc6d70683
parent 544 5550c3ba96ba
child 589 48dde9218263
permissions -rw-r--r--
1.9.4 New base class for XML based file parsing (vym & Freemind)
insilmaril@509
     1
\documentclass[12pt,a4paper]{article}
insilmaril@509
     2
\usepackage[utf8]{inputenc}
insilmaril@28
     3
\usepackage{verbatim}
insilmaril@28
     4
\usepackage{hyperref}
insilmaril@28
     5
\usepackage{graphicx}
insilmaril@493
     6
%\usepackage{longtable}
insilmaril@28
     7
insilmaril@509
     8
\setlength{\headheight}{0cm}
insilmaril@509
     9
\setlength{\headsep}{0cm}
insilmaril@509
    10
\setlength{\topskip}{0cm}
insilmaril@509
    11
\setlength{\topmargin}{-0.5cm}
insilmaril@509
    12
insilmaril@509
    13
\setlength{\parskip}{1.5ex}
insilmaril@509
    14
\setlength{\parindent}{0cm}
insilmaril@509
    15
\setlength{\oddsidemargin}{0cm}
insilmaril@509
    16
\setlength{\textwidth}{16cm}
insilmaril@509
    17
\setlength{\textheight}{27cm}
insilmaril@509
    18
insilmaril@509
    19
\newlength{\maximgwidth}
insilmaril@509
    20
\setlength{\maximgwidth}{14cm}
insilmaril@509
    21
\newcommand{\maximage}[1]{	
insilmaril@509
    22
	\begin{center}
insilmaril@509
    23
		\includegraphics[width=\maximgwidth]{#1} 
insilmaril@509
    24
	\end{center}
insilmaril@509
    25
}
insilmaril@509
    26
\newcommand{\hint}[1]{
insilmaril@514
    27
	\begin{center} 
insilmaril@509
    28
		\begin{tabular}{|rp{12cm}|} \hline
insilmaril@509
    29
			{\bf Hint}:& #1\\	\hline
insilmaril@509
    30
		\end{tabular}
insilmaril@514
    31
			\marginpar{\Huge !} 
insilmaril@514
    32
	\end{center} 
insilmaril@509
    33
}
insilmaril@509
    34
insilmaril@509
    35
\newcommand{\vym}{{\sc vym }}
insilmaril@509
    36
\newcommand{\ra}{$\longrightarrow$}
insilmaril@509
    37
\newcommand{\la}{$\longleftarrow$}
insilmaril@509
    38
\newcommand{\ua}{$\uparrow$}
insilmaril@509
    39
\newcommand{\da}{$\downarrow$}
insilmaril@509
    40
\newcommand{\key}[1]{[#1]}
insilmaril@509
    41
insilmaril@514
    42
\newenvironment{code}[1] { \verbatim #1}{\endverbatim  }
insilmaril@514
    43
insilmaril@28
    44
\hypersetup{bookmarks, bookmarksopen,
insilmaril@28
    45
  pdftitle={VYM - a tool for visual thinking },
insilmaril@28
    46
  pdfauthor={Uwe Drechsel},    
insilmaril@28
    47
  pdfsubject={map},
insilmaril@28
    48
  pdfkeywords={map, tool},
insilmaril@28
    49
  pdfpagemode={UseOutlines},                                 
insilmaril@28
    50
  bookmarksopenlevel={1},   
insilmaril@28
    51
  colorlinks={true},     
insilmaril@28
    52
  linkcolor={blue},
insilmaril@28
    53
  urlcolor={green},
insilmaril@28
    54
  citecolor={red}} 
insilmaril@28
    55
insilmaril@28
    56
insilmaril@28
    57
\begin{document}
insilmaril@233
    58
\title{
insilmaril@450
    59
	\includegraphics[width=8cm]{images/vym-logo-new.png}
insilmaril@233
    60
	\\
insilmaril@493
    61
VYM \\ -- \\View Your Mind\\ {\small Version 1.9.0}}
insilmaril@28
    62
\author{\textcopyright Uwe Drechsel  }
insilmaril@28
    63
insilmaril@233
    64
insilmaril@28
    65
\maketitle
insilmaril@28
    66
insilmaril@233
    67
\newpage
insilmaril@233
    68
insilmaril@28
    69
\tableofcontents
insilmaril@28
    70
insilmaril@28
    71
\newpage
insilmaril@28
    72
insilmaril@540
    73
\section*{Credits}
insilmaril@540
    74
Many people have sent me their feedback and ideas, and all of that has
insilmaril@540
    75
helped a lot to make \vym better. Thanks to all of you!
insilmaril@540
    76
insilmaril@540
    77
For this manual I would like to send some special thanks to
insilmaril@540
    78
insilmaril@540
    79
\begin{itemize}
insilmaril@540
    80
	\item {\em Peter Adamson} for lots of feedback and proofreading of my
insilmaril@540
    81
	      far from perfect english
insilmaril@540
    82
	\item The team of {\em AClibre (Academia y Conocimiento Libre)}
insilmaril@540
    83
          in Colombia for their translation of
insilmaril@540
    84
          the manual to spanish:
insilmaril@540
    85
		  \begin{center}
insilmaril@540
    86
			\begin{tabular}{|p{7cm}|p{5.5cm}|} \hline
insilmaril@540
    87
				Encargado & Actividad \\ \hline
insilmaril@540
    88
				\begin{itemize}
insilmaril@540
    89
				   \item Vanessa Carolina Guti\'errez Sanchez
insilmaril@540
    90
				   \item Erika Tatiana Luque Melo
insilmaril@540
    91
				   \item Jeffrey Steve Borb\'on Sanabria
insilmaril@540
    92
				   \item John Edisson Ortiz Rom\'an
insilmaril@540
    93
				\end{itemize} &
insilmaril@540
    94
				\begin{itemize}
insilmaril@540
    95
					\item Traducci\'onl
insilmaril@540
    96
					\item Revisi\'on y correcciones varias
insilmaril@540
    97
					\item Estructuraci\'on y exporte
insilmaril@540
    98
					\item Revisi\'on y correcciones varias
insilmaril@540
    99
				\end{itemize}     \\ \hline
insilmaril@540
   100
			\end{tabular}	
insilmaril@540
   101
		\end{center}
insilmaril@540
   102
\end{itemize}
insilmaril@540
   103
\newpage
insilmaril@540
   104
insilmaril@540
   105
insilmaril@28
   106
\section{Introduction}
insilmaril@28
   107
\subsection{What is a \vym map?}
insilmaril@486
   108
A \vym map (abbreviated below as {\em map}) is a tree like structure:
insilmaril@509
   109
\maximage{images/example1.png}
insilmaril@486
   110
Such maps can be drawn by hand on a sheet of paper or flip chart and help to
insilmaril@486
   111
structure your thoughts. While a tree like structure like the illustration above can be
insilmaril@264
   112
drawn manually \vym offers much more features to work with such maps.
insilmaril@486
   113
\vym is not just another drawing software application, but a tool to store and modify
insilmaril@264
   114
information in an intuitive way. For example you can reorder parts of
insilmaril@486
   115
the map by pressing a key or add various pieces of information like a complete
insilmaril@264
   116
email by a simple mouse click.
insilmaril@264
   117
insilmaril@486
   118
Once you have finished collecting and organising your ideas, you can
insilmaril@509
   119
easily generate a variety of outputs including for example a
insilmaril@509
   120
presentation in Open~Office based on a {\em map}.
insilmaril@509
   121
insilmaril@509
   122
\hint{You find the map shown above and others by clicking \begin{center}Help \ra Open vym
insilmaril@509
   123
examples\end{center} in the menu bar.}
insilmaril@28
   124
insilmaril@486
   125
\subsection{Why should I use {\em maps}? Time, Space and your Brain.}
insilmaril@28
   126
\subsubsection*{Space}
insilmaril@486
   127
A {\em map} can concentrate very complex content in a small space such as a
insilmaril@28
   128
piece of paper. It helps to use both sides of your brain: the logical
insilmaril@486
   129
side and also your creative side (e.g. by using pictures, colours and
insilmaril@486
   130
keywords in a map, often called {\em anchors}).  It is a technique to help
insilmaril@486
   131
organize the way you think and stimulate your creativity: It can help you by developing, sorting and helping to memorise your ideas. 
insilmaril@28
   132
insilmaril@28
   133
\subsubsection*{Time}
insilmaril@28
   134
Because you just use keywords and drawings, it is much faster than good
insilmaril@486
   135
old fashioned 'notes'. Your brain memorizes things by associating them with
insilmaril@486
   136
other things -- a {\em map} makes use of those connections and stimulates
insilmaril@28
   137
new asccociations. 
insilmaril@28
   138
insilmaril@125
   139
insilmaril@28
   140
\subsubsection*{Your Brain}
insilmaril@486
   141
In 1960 Prof. {\sc Roger Sperry} discovered that both hemispheres
insilmaril@486
   142
of the human brain undertake different tasks (of course both of them
insilmaril@125
   143
basically {\em can} do the same): 
insilmaril@125
   144
\begin{center}
insilmaril@125
   145
\begin{tabular}{|p{5.5cm}|p{5.5cm}|} \hline
insilmaril@125
   146
	Left side & Right side \\ \hline
insilmaril@125
   147
	\begin{itemize}
insilmaril@125
   148
	   \item verbal speech and writing 
insilmaril@125
   149
	   \item numbers
insilmaril@125
   150
	   \item logical thinking
insilmaril@486
   151
	   \item analysing and details
insilmaril@125
   152
	   \item science
insilmaril@125
   153
	   \item linear thinking
insilmaril@125
   154
	   \item concept of time
insilmaril@125
   155
	\end{itemize} &
insilmaril@125
   156
	\begin{itemize}
insilmaril@125
   157
		\item body language
insilmaril@125
   158
		\item visual thinking, day dreams
insilmaril@125
   159
		\item intuition and emotion
insilmaril@125
   160
		\item overview of things
insilmaril@125
   161
		\item creativity
insilmaril@125
   162
		\item art, music, dancing
insilmaril@125
   163
		\item non-linear thinking, connecting things
insilmaril@125
   164
		\item spatial awareness
insilmaril@125
   165
	\end{itemize}     \\ \hline
insilmaril@125
   166
\end{tabular}	
insilmaril@125
   167
\end{center}
insilmaril@486
   168
In our science oriented western society we have learned to mainly rely on our
insilmaril@486
   169
left side of the brain, the "rational" one. In other cultures, such as the native americans and other "old" cultures, the right
insilmaril@486
   170
side is much more important. {\em Map} are just one way to stimulate the
insilmaril@486
   171
other side and make use of additional resources we all have.
insilmaril@28
   172
insilmaril@28
   173
insilmaril@486
   174
\subsection{Where could I use a {\em map}?}
insilmaril@486
   175
Here are some examples, how you can use those {\em maps}
insilmaril@28
   176
\begin{itemize}
insilmaril@28
   177
    \item to prepare articles, papers, books, talks, \ldots
insilmaril@28
   178
    \item to sort complex data
insilmaril@486
   179
    \item to memorize facts, peoples names, vocabulary, \ldots
insilmaril@28
   180
    \item to sort emails, files and bookmarks on your computer
insilmaril@28
   181
    \item to moderate conferences
insilmaril@486
   182
    \item to brainstorm solutions to problems
insilmaril@486
   183
    \item to record the tasks when planning a project
insilmaril@28
   184
\end{itemize}
insilmaril@28
   185
insilmaril@486
   186
\subsection{What you shouldn't do with a {\em map}...}
insilmaril@486
   187
A {\em map} drawn by somebody shows the way that the author thinks. There is
insilmaril@486
   188
no question of right or wrong in the way it is drawn, so there is no way to criticise
insilmaril@486
   189
it. "It is, what it is" ({\sc F.~Lehmann}).The tool will be of considerable use to the author and only very limited use to anyone else. 
insilmaril@486
   190
insilmaril@486
   191
However, when groups share in creating a {\em map} all of the group will benefit from its use. An example of such use is when a Tutor develops a {\em map} with a group of students during instruction. Another group use is when a Project leader gathers a group of specialists to help {\em map} the tasks that will be required to deliver a project.
insilmaril@28
   192
insilmaril@28
   193
%\section{Tutorials}
insilmaril@28
   194
%TODO
insilmaril@28
   195
insilmaril@125
   196
\subsection{Internet Ressources} 
insilmaril@486
   197
A good starting point to learn more about Mindmaps in general is Wikipedia:
insilmaril@125
   198
\begin{itemize}
insilmaril@125
   199
	\item English: 
insilmaril@125
   200
		\href{http://en.wikipedia.org/wiki/Mind_map}{http://en.wikipedia.org/wiki/Mind\_map}
insilmaril@125
   201
	\item German: 
insilmaril@125
   202
		\href{http://de.wikipedia.org/wiki/Mindmap}{http://de.wikipedia.org/wiki/Mindmap}
insilmaril@125
   203
\end{itemize}
insilmaril@125
   204
insilmaril@28
   205
insilmaril@245
   206
insilmaril@245
   207
insilmaril@486
   208
\section{The Concept of the \vym application}
insilmaril@28
   209
%TODO may add a general introduction here...
insilmaril@493
   210
\subsection{The Mainwindow and its satellites} \label{satellite}
insilmaril@493
   211
\vym comes with several windows, the central one being the {\em
insilmaril@493
   212
mapeditor}.
insilmaril@493
   213
More windows, each having a special purpose, can be opened and arranged
insilmaril@493
   214
around the mainwindow\footnote{
insilmaril@493
   215
	The advantage of having separate window instead of integrating them
insilmaril@493
   216
	in a combined workspace is flexibility in arranging the windows. For
insilmaril@493
   217
	example I usually have the {\em noteeditor} "behind" the {\em
insilmaril@493
   218
	mapeditor}. On Linux my windowmanager (KDE) allows me to enter text
insilmaril@493
   219
	into a small visible corner of the {\em noteeditor} withour clicking
insilmaril@493
   220
	the mouse button in it. I just push the mouse around to set the
insilmaril@493
   221
	window focus, a concept which is useful also working with 
insilmaril@493
   222
	\href{http://www.gimp.org}{http://www.gimp.org}.
insilmaril@493
   223
}. 
insilmaril@493
   224
The image below shows the {\em mapeditor}
insilmaril@493
   225
together with the often used {\em noteeditor}: 
insilmaril@509
   226
\maximage{images/windows.png}
insilmaril@486
   227
Most of the time you will work in the {\em mapeditor} by just adding new
insilmaril@28
   228
branches, moving around and reordering them. The various ways to do this
insilmaril@28
   229
will be explained in \ref{mapeditor}. You can store additional
insilmaril@28
   230
information e.g. the content of a email easily in a {\em branch}: Just
insilmaril@28
   231
type or copy\&paste it into the {\em noteeditor}. Working with notes is
insilmaril@28
   232
explained in \ref{noteeditor}
insilmaril@420
   233
 
insilmaril@493
   234
Here is a list of the available satellite windows:
insilmaril@493
   235
\begin{itemize}
insilmaril@493
   236
	\item Noteeditor (see \ref {noteeditor})
insilmaril@493
   237
	\item Historywindow (see \ref{historywindow})
insilmaril@493
   238
	\item Branch Property Window (see \ref{propwindow})
insilmaril@493
   239
\end{itemize}
insilmaril@493
   240
insilmaril@28
   241
insilmaril@245
   242
\subsection{Menus and Context menus}
insilmaril@486
   243
At the top of each window you will find the menubar. The options provided there
insilmaril@486
   244
are similar to those you are probably used to from other applications. Note that
insilmaril@245
   245
many (and even more) options are availabe via {\em context menus}. Those
insilmaril@245
   246
are available if you right-click onto an object in a map (on Mac~OS~X
insilmaril@245
   247
Command-Click).
insilmaril@245
   248
insilmaril@245
   249
\subsection{Toolbars}
insilmaril@245
   250
The toolbars in the mainwindows give quick access to many functions and
insilmaril@493
   251
also display the state of selected objects in the map. For example a
insilmaril@493
   252
branch may show certain {\em flags}, the corresponding flags are also
insilmaril@493
   253
set in the toolbar. 
insilmaril@245
   254
insilmaril@509
   255
\hint {You can reposition all toolbars by simply grabbing and
insilmaril@493
   256
dragging them with the toolbar handle to a new position. For example you
insilmaril@493
   257
can move the flags-toolbar from its original horizontal position on top
insilmaril@493
   258
of the mapeditor to a vertical position on the right side.  Or just
insilmaril@493
   259
insert it again at its original position. Also hiding some of the
insilmaril@509
   260
toolbars is possible by right-clicking on the toolbar handle.}
insilmaril@245
   261
insilmaril@245
   262
\subsection{Maps}
insilmaril@486
   263
The  {\em map} itself has always a {\em mapcenter}.  The
insilmaril@509
   264
mapcenter has {\em branches} radiating out from the centre just like the trunk 
insilmaril@509
   265
of a tree. Each branch in turn may have branches again.
insilmaril@509
   266
	\maximage{images/branches.png}
insilmaril@28
   267
We will call a branch directly connected to the mapcenter a {\em
insilmaril@28
   268
mainbranch}, because it determines the position of all its child
insilmaril@28
   269
branches.
insilmaril@28
   270
insilmaril@28
   271
The mapcenter and the branches all have a {\em heading}. This is the
insilmaril@28
   272
text you see in the mapeditor. Usually it should just be one or a few
insilmaril@486
   273
key words, so that one can easily keep track of the whole map.
insilmaril@28
   274
insilmaril@28
   275
insilmaril@28
   276
In the toolbar above the mapeditor you see various symbols.
insilmaril@509
   277
	\maximage{images/default-flags.png}
insilmaril@28
   278
These are called {\em flags} and can be used to mark branches in the
insilmaril@486
   279
{\em map}, e.g. if something is important or questionable. 
insilmaril@28
   280
There are also more flags set by \vym automatically to show additional
insilmaril@486
   281
information, e.g. when a note is attached to a  particular branch.
insilmaril@28
   282
insilmaril@260
   283
By default some of these flags are set exclusively e.g. when the 
insilmaril@486
   284
"thumb-up" flag is set, then the "thumb down" is reset and vice
insilmaril@544
   285
versa. You can change this default behaviour in the settings menu (see
insilmaril@544
   286
\ref{settings}).
insilmaril@104
   287
insilmaril@28
   288
\section{Mapeditor} \label {mapeditor}
insilmaril@28
   289
\subsection{Start a new map}
insilmaril@486
   290
After \vym is started two windows will open: the {\em mapeditor} and the {\em noteditor}. Usually you will work in both windows, but at the moment we
insilmaril@28
   291
will just need the mapeditor. 
insilmaril@28
   292
insilmaril@28
   293
Select the mapcenter "New map" in the middle of the mapeditor by
insilmaril@486
   294
left-clicking with the mouse. It will be highlighted yellow to show that is
insilmaril@103
   295
selected. There are several ways to add a new branch to the center:
insilmaril@28
   296
\begin{itemize}
insilmaril@486
   297
	\item Using the mouse: Open the context menu by clicking with the
insilmaril@103
   298
	right mouse button (CTRL-Click on Mac) onto the
insilmaril@486
   299
	mapcenter and choose Add \ra Add branch as child
insilmaril@103
   300
	\item Press \key{Ins} or \key{A}
insilmaril@28
   301
\end{itemize}
insilmaril@28
   302
A new branch will appear and you will be able to type the heading of the
insilmaril@28
   303
branch. Finish adding the new branch by pressing \key{Enter}.
insilmaril@28
   304
%tipp
insilmaril@486
   305
Sometimes it comes in handy to be able to add a new branch above or below the current
insilmaril@486
   306
one. 
insilmaril@486
   307
\begin{itemize}
insilmaril@509
   308
	\item Use \key{Shift-A} to add a branch above the selected one or... 
insilmaril@509
   309
	\item \key{Ctrl-A} to add one below. 
insilmaril@486
   310
\end{itemize}
insilmaril@486
   311
It is also
insilmaril@104
   312
possible to add a branch in such a way, that the current selection
insilmaril@104
   313
becomes the child of the new branch, which is like inserting it {\em
insilmaril@104
   314
before} the selection. This can be done using the context menu.
insilmaril@28
   315
insilmaril@509
   316
\hint{To delete a branch press \key{CTRL-X}. If enabled in the Settings
insilmaril@544
   317
menu (see \ref{settings}), you can also use the \key{Del} key.}
insilmaril@509
   318
insilmaril@28
   319
\subsection{Navigate through a map}
insilmaril@28
   320
\subsubsection*{Select branches}
insilmaril@28
   321
To select branches you can use the left button of your mouse or also the
insilmaril@486
   322
arrow keys. Depending on the {\em orientation} of a branch tap
insilmaril@486
   323
\key{\la} or \key{\ra} to move nearer to the mapcenter or deeper
insilmaril@28
   324
down into the branches. Within a set of branches, let's call them a 
insilmaril@28
   325
{\em subtree}, you can use \key{\ua} and \key{\da} to go up and down. You can
insilmaril@486
   326
also use \key{Home} and \key{End} to select the first and last branch.
insilmaril@28
   327
insilmaril@28
   328
insilmaril@486
   329
\subsubsection*{Panning the view of a map}
insilmaril@28
   330
While adding more and more branches the size of the map may become
insilmaril@486
   331
larger than the mapeditor window. You can use the scrollbars on the
insilmaril@486
   332
right and the bottom of your mapeditor window to scroll the view up or down or left or right. It is easier to just scroll using the left mouse button: Click anywhere on the {\em canvas} itself. Choose an empty space somewhere between the branches. The
insilmaril@486
   333
mouse pointer will change from an arrow to a hand, now move or drag the visible
insilmaril@486
   334
map to show the desired part.
insilmaril@28
   335
insilmaril@28
   336
If you select branches using the arrow keys, the map will scroll
insilmaril@28
   337
to ensure that the selected branch is always visible.
insilmaril@28
   338
insilmaril@486
   339
\subsubsection*{Zooming the view of a map}
insilmaril@28
   340
Working with huge maps, the {\em zoom}-function comes in handy: You can
insilmaril@28
   341
use 
insilmaril@28
   342
\begin{itemize}
insilmaril@486
   343
	\item from the menu: View \ra Zoom in, View \ra Zoom out, View \ra reset Zoom.
insilmaril@28
   344
	\item the toolbar buttons 
insilmaril@28
   345
		\begin{center}
insilmaril@450
   346
			\includegraphics[width=3cm]{images/zoom-buttons.png}
insilmaril@28
   347
		\end{center}	
insilmaril@28
   348
\end{itemize}	
insilmaril@486
   349
Clicking the crossed magnifying lens icon will reset the zoomed view to its original size.
insilmaril@28
   350
insilmaril@28
   351
insilmaril@28
   352
\subsubsection*{Find Function} \label{findwindow}
insilmaril@28
   353
With huge maps there is the need to have a
insilmaril@28
   354
find function. Choose Edit \ra Find to open the Find Window:
insilmaril@28
   355
\begin{center}
insilmaril@450
   356
	\includegraphics[width=6cm]{images/find-window.png}
insilmaril@28
   357
\end{center}	
insilmaril@486
   358
The find function will search for, the text you enter here, in all the branch headings and also in the associated notes. Everytime you press the "Find"-button it will look for the next occurence, which will then be selected automatically. If the search
insilmaril@486
   359
fails, a short message "Nothing found" will appear for a few
insilmaril@28
   360
seconds in the {\em statusbar} on the bottom of the mapeditor.
insilmaril@28
   361
insilmaril@260
   362
\subsubsection*{Keep the overview -- scroll a part of the map}
insilmaril@486
   363
A very big subtree of a map e.g. a branch with hundreds of child branches would make
insilmaril@28
   364
it very hard to keep an overview over the whole map. You can hide all
insilmaril@486
   365
the children of a branch by {\em scrolling} it -- this function is often called {\em folding}. Think of the whole subtree as painted onto a
insilmaril@486
   366
broadsheet newspaper. You can scroll or fold the paper to a small roll, leaving just
insilmaril@486
   367
the headline visible.
insilmaril@28
   368
insilmaril@486
   369
To scroll or unscroll a branch and its children,
insilmaril@28
   370
\begin{itemize}
insilmaril@486
   371
	\item press either the \key{Scroll Lock} key or the \key{S}
insilmaril@28
   372
	\item press the middle-mouse button or
insilmaril@486
   373
	\item choose the scroll icon from the toolbar.
insilmaril@28
   374
\end{itemize}
insilmaril@28
   375
If you select parts of a scrolled branch e.g. using the find function or
insilmaril@28
   376
by using the arrow-keys, it will unscroll temporary. This is shown as a
insilmaril@486
   377
scroll with a little hour glass. If the temporary unscrolled part is no
insilmaril@28
   378
longer needed, it will be hidden again automatically. It is also
insilmaril@486
   379
possible to unscroll all branches using "Edit\ra Unscroll all scrolled
insilmaril@486
   380
branches".
insilmaril@28
   381
insilmaril@264
   382
You can also hide parts of the map while exporting it e.g. to a webpage
insilmaril@264
   383
or a presentation, see \ref{hideexport} for details.
insilmaril@28
   384
insilmaril@28
   385
\subsection{Modify and move branches}
insilmaril@260
   386
\subsubsection*{Modify the heading}
insilmaril@28
   387
You can edit the heading by selecting the branch and then
insilmaril@28
   388
\begin{itemize}
insilmaril@28
   389
	\item pressing \key{Enter}
insilmaril@486
   390
	\item pressing \key{F2}
insilmaril@28
   391
	\item double-clicking with left mouse.
insilmaril@28
   392
\end{itemize}
insilmaril@28
   393
Just type the new heading (or edit the old one) and press \key{Enter}.
insilmaril@28
   394
insilmaril@28
   395
\subsubsection*{Move a branch}
insilmaril@28
   396
The easiest way to move a branch is to select it with left-mouse and
insilmaril@28
   397
drag it to the destination while keeping the mouse button pressed.
insilmaril@28
   398
Depending on the branch  it will be
insilmaril@28
   399
\begin{itemize}
insilmaril@28
   400
	\item moved to the destination or
insilmaril@28
   401
	\item {\em linked} to a new {\em parent} (mapcenter or branch)
insilmaril@28
   402
\end{itemize}
insilmaril@28
   403
If you drag the branch over another one or over the mapcenter, you will
insilmaril@28
   404
notice that the  link connecting it to the old parent will be changed to
insilmaril@28
   405
lead to the  new parent which is now under your mousepointer. 
insilmaril@28
   406
If you release the button now, the branch will be relinked.
insilmaril@28
   407
insilmaril@28
   408
If you release the button in the middle of nowhere, the result will
insilmaril@28
   409
depend on the type of branch you are releasing:
insilmaril@28
   410
\begin{itemize}
insilmaril@28
   411
	\item A mainbranch is directly connected to the mapcenter.
insilmaril@28
   412
		It will stay on its new position.
insilmaril@28
   413
	\item An ordinary branch will "jump" back to its original position.	
insilmaril@28
   414
\end{itemize}
insilmaril@28
   415
Thus you can easily rearrange the layout of the mainbranches to avoid
insilmaril@28
   416
overlapping of their subtrees.
insilmaril@28
   417
There is another convenient way to move branches, especially if you want
insilmaril@28
   418
to {\em reorder} a subtree: You can move a branch up or down in a
insilmaril@28
   419
subtree by
insilmaril@28
   420
\begin{itemize}
insilmaril@28
   421
	\item pressing \key{\ua} and \key {\da}
insilmaril@28
   422
	\item selecting Edit \ra Move branch
insilmaril@28
   423
	\item clicking on the toolbar buttons:
insilmaril@28
   424
		\begin{center}
insilmaril@450
   425
			\includegraphics[width=1.5cm]{images/move-buttons.png}
insilmaril@28
   426
		\end{center}	
insilmaril@28
   427
\end{itemize}
insilmaril@28
   428
%tipp
insilmaril@28
   429
There is yet another way to move branches: If you press \key{Shift} or
insilmaril@28
   430
\key{Ctrl} while moving with the mouse, the branch will be added above
insilmaril@486
   431
or below the one the mouse pointer is over. This can also be used to reorder branches in a map.
insilmaril@28
   432
insilmaril@486
   433
\subsection{Colours and Images - Using the right side of your brain}
insilmaril@486
   434
\subsubsection*{Change colour of a heading}
insilmaril@486
   435
You can also use colours to add more information to a map, e.g. use
insilmaril@486
   436
red, green and more colours to prioritize tasks. Again you can
insilmaril@28
   437
\begin{itemize}
insilmaril@486
   438
	\item use the menu and choose e.g Format \ra Set Color
insilmaril@28
   439
	\item use the toolbar
insilmaril@28
   440
		\begin{center}
insilmaril@493
   441
			\includegraphics[width=3cm]{images/color-buttons.png}
insilmaril@28
   442
		\end{center}	
insilmaril@28
   443
\end{itemize}
insilmaril@486
   444
The first button (black in the graphic above) shows the current colour.
insilmaril@486
   445
Clicking on it let's you choose another colour. You can also "pick"
insilmaril@486
   446
another colour by selecting a branch with the desired colour and using the
insilmaril@486
   447
"pick colour" button. Both of the icons showing a palette actually apply
insilmaril@486
   448
the current colour to the selected branch. While the first one just
insilmaril@486
   449
colours the heading of the selection, the last one also colours all the
insilmaril@486
   450
children of the selected branch.
insilmaril@28
   451
insilmaril@28
   452
%tipp
insilmaril@486
   453
A very useful function is the "copy colour" using the mouse: Select the
insilmaril@486
   454
branch which should get the new colour, then press \key{Ctrl} and
insilmaril@486
   455
simultanously click with left-mouse on another branch to copy its colour
insilmaril@486
   456
to the first one. Here the children of the selection also will get the new
insilmaril@486
   457
colour, if you just want to colour the selection itself, additionally
insilmaril@28
   458
press \key{Shift}.
insilmaril@28
   459
insilmaril@28
   460
\subsubsection*{Use flags}
insilmaril@486
   461
\vym provides various flags. They are usually displayed in the toolbar on top of the
insilmaril@28
   462
mapeditor window. (Note: Like all toolbars you can also move them to the
insilmaril@28
   463
left or the right side of the window or even detach them. Just grab the
insilmaril@28
   464
very left "dotted" part of the toolbar with your left-mouse button.) 
insilmaril@509
   465
	\maximage{images/default-flags.png}
insilmaril@28
   466
If you have a branch selected, you can set any number of flags by
insilmaril@28
   467
clicking them in the toolbar. The toolbar buttons change their state and
insilmaril@486
   468
always reflect the flags set in the selected branch. So, to remove a flag from a branch, select the branch and then click the highlighted flag on the toolbar.
insilmaril@28
   469
insilmaril@486
   470
At present \vym uses two kinds of flags: {\em System Flags} and {\em
insilmaril@28
   471
Standard Flags}. The standard flags are those shown in the toolbar.
insilmaril@28
   472
System flags are set by \vym to indicate e.g. that there is additional
insilmaril@28
   473
information in a note (more on this in \ref{noteeditor}). Later versions
insilmaril@28
   474
of \vym may have another kind of flags, which may be edited by the user.
insilmaril@28
   475
insilmaril@28
   476
\subsubsection*{Images}
insilmaril@125
   477
The easiest way to add an image to a branch is by dragging it e.g. from a
insilmaril@125
   478
webbrowser to the mapeditor while a branch is selected there.
insilmaril@125
   479
insilmaril@486
   480
You can also add an image to a branch by opening the context menu of the
insilmaril@493
   481
branch. Right click the selected branch, choose "Add Image". A
insilmaril@486
   482
dialog window enables you choose the image to load. 
insilmaril@28
   483
\footnote{Supported image types are: PNG, BMP, XBM, XPM and PNM. It may
insilmaril@28
   484
	also support JPEG, MNG and GIF, if specially configured during
insilmaril@28
   485
	compilation (as done when \vym is part of SUSE LINUX).}
insilmaril@486
   486
While an image is selected in the dialog, a preview of the
insilmaril@486
   487
image is displayed. It is also possible to select multiple images.	
insilmaril@28
   488
insilmaril@28
   489
You can position the image anywhere you want, just drag it with left
insilmaril@28
   490
mouse. To relink it to another branch, press \key{Shift} while moving
insilmaril@28
   491
it. To delete it, press \key{Del}. 
insilmaril@28
   492
insilmaril@28
   493
If you right-click onto an image, a context menu will open which let's
insilmaril@28
   494
you first choose one of several image formats. Then a file dialog opens
insilmaril@486
   495
to save the image. 
insilmaril@486
   496
insilmaril@486
   497
Hint: This is used to "export" the image, it will be
insilmaril@28
   498
saved anyway in the map itself! You can also cut and
insilmaril@28
   499
copy images, but it is not possible to add objects to an image\footnote{
insilmaril@28
   500
	Images are regarded as "extra feature". It would make working with
insilmaril@28
   501
	the map much more complex if e.g. images could be linked to images.}
insilmaril@28
   502
insilmaril@28
   503
The option \lq{\bf Use for export} \rq controls the output of exports
insilmaril@28
   504
e.g. to HTML: If set to no, the image won't appear in the {\em text}
insilmaril@28
   505
part of the output. This is useful for large images or if images are
insilmaril@28
   506
used as a kind of frame e.g. the famous cloud symbol around a part of
insilmaril@28
   507
the map. Those shouldn't appear in the middle of the text.
insilmaril@28
   508
insilmaril@28
   509
At the moment image support is preliminary: Images will be saved
insilmaril@28
   510
together with all the other data of a map in the {\tt .vym}-file.
insilmaril@28
   511
Later versions will include more functionality like resizing the images,
insilmaril@28
   512
changing its z-value (put it into background) etc.
insilmaril@28
   513
insilmaril@28
   514
\subsubsection*{Frames}
insilmaril@493
   515
A frame can be added to a branch in the {\em property window} (see
insilmaril@493
   516
\ref{propwindow}). 
insilmaril@493
   517
Alternatively, you can use use images as frames. Have a look at the demo
insilmaril@493
   518
map {\tt todo.vym} as an example, where the mapcenter is a cloud. You
insilmaril@493
   519
can use an external drawing program like {\tt gimp} to create an image,
insilmaril@28
   520
preferable with an transparency channel, so that you can design frames
insilmaril@493
   521
which don't use a rectangular borderline, just like that cloud.
insilmaril@28
   522
insilmaril@28
   523
insilmaril@493
   524
\subsection{Design of map background and connecting links }
insilmaril@28
   525
The design of the background of a map and also of the links connecting
insilmaril@28
   526
various parts of the map can be changed by
insilmaril@28
   527
\begin{itemize}
insilmaril@28
   528
	\item Selecting Format from the menu
insilmaril@486
   529
	\item Right clicking on the canvas, which will open a context menu
insilmaril@28
   530
\end{itemize}
insilmaril@28
   531
insilmaril@493
   532
\subsubsection*{Background }
insilmaril@486
   533
The colour is set (and also displayed) as "Set background colour".
insilmaril@493
   534
Alternatevily you can set an background image, though this is not
insilmaril@493
   535
recommended in general. Working on the map becomes slow and the image
insilmaril@493
   536
currently cannot be positioned freely.
insilmaril@28
   537
insilmaril@486
   538
\subsubsection*{Link colour}
insilmaril@486
   539
Links connecting branches can be coloured in one of two ways:
insilmaril@28
   540
\begin{itemize}
insilmaril@486
   541
	\item use the same colour for the heading and for the branch link line.
insilmaril@486
   542
	\item use {\em one} colour for all links and choose different colours for the branch headings text. The default colour for branch link lines is blue.
insilmaril@28
   543
\end{itemize}
insilmaril@486
   544
The latter can be set with "Set link colour". Check or uncheck the "Use
insilmaril@486
   545
colour of heading for link" option to toggle between the two designs for
insilmaril@28
   546
your map.
insilmaril@28
   547
insilmaril@28
   548
\subsubsection*{Link style}
insilmaril@28
   549
\vym offers four different styles for the appearences of links:
insilmaril@28
   550
\begin{itemize}
insilmaril@28
   551
	\item Line
insilmaril@28
   552
	\item Parabel
insilmaril@28
   553
	\item Thick Line
insilmaril@28
   554
	\item Thick Parabel
insilmaril@28
   555
\end{itemize}
insilmaril@486
   556
The "thick" styles only apply to links starting at the mapcenter, link lines for the rest
insilmaril@486
   557
of the map are always painted "thin".
insilmaril@28
   558
insilmaril@28
   559
insilmaril@260
   560
\subsection{Links to other documents and webpages}
insilmaril@260
   561
\vym supports two kind of external links:
insilmaril@28
   562
\begin{itemize}
insilmaril@28
   563
	\item Document, which will be opened in an external webbrowser
insilmaril@28
   564
	\item \vym map, which will be opened in \vym itself
insilmaril@28
   565
\end{itemize}
insilmaril@260
   566
In addition to the external links there also internal ones, leading from one
insilmaril@486
   567
branch in a map to another one. Those are called {\em XLinks} and are explained
insilmaril@260
   568
in section~\ref{xlinks}.
insilmaril@28
   569
insilmaril@28
   570
\subsubsection*{Webbrowser}
insilmaril@486
   571
Modern Webbrowsers like {\tt konqueror and Firefox} are able to display various
insilmaril@486
   572
types of files, both local or on the internet. To enter the URL of
insilmaril@528
   573
any document, press \key{U} or right-click  onto a branch to open the contextmenu then choose
insilmaril@528
   574
"References\ra Edit URL". If you want to use a file dialog to
insilmaril@528
   575
conveniently choose a local file you can use~\key{SHIFT-U}.
insilmaril@528
   576
insilmaril@528
   577
After an URL was entered, a little globe will appear in the branch. By
insilmaril@28
   578
clicking on the globe in the toolbar or the context menu an external
insilmaril@28
   579
browser\footnote{
insilmaril@544
   580
	The browser can be changed in the Settings Menu (see \ref{settings}).}
insilmaril@486
   581
will be launched.
insilmaril@28
   582
\begin{center}
insilmaril@450
   583
	\includegraphics[width=0.5cm]{images/flag-url.png}
insilmaril@28
   584
\end{center}
insilmaril@340
   585
For more information on working with bookmarks and webbrowsers see
insilmaril@340
   586
section \ref{bookmarks}.
insilmaril@266
   587
insilmaril@493
   588
In the context menu there is also an option to open all URLs found
insilmaril@493
   589
in the selected subtree of the map. That's useful to simultanously open
insilmaril@493
   590
a collection of URLs in the webbrowser, especially if the browser can
insilmaril@493
   591
open them in tabs (like Konqueror).
insilmaril@493
   592
insilmaril@28
   593
insilmaril@28
   594
\subsubsection*{\vym map}
insilmaril@486
   595
To link to to another map right click on a branch and choose "Edit \vym link". A file dialog opens where you can choose the map. A
insilmaril@28
   596
branch with a link is marked with 
insilmaril@28
   597
\begin{center}
insilmaril@450
   598
	\includegraphics[width=0.5cm]{images/flag-vymlink.png}
insilmaril@28
   599
\end{center}
insilmaril@486
   600
Clicking this flag beside the branch heading, in the toolbar or in the context menu of a branch will open the map in another tab (see \ref{tabs} for working with
insilmaril@486
   601
multiple maps). To delete an existing link, just right click the branch and select "Delete \vym link".
insilmaril@28
   602
insilmaril@493
   603
In the context menu there is also an option to open all vymlinks found
insilmaril@493
   604
in the selected subtree of the map. That's useful to simultanously open
insilmaril@493
   605
a collection of related maps.
insilmaril@493
   606
insilmaril@28
   607
Technical note: Internally \vym uses absolute paths, to avoid opening
insilmaril@28
   608
several tabs containing the same map. When a map is saved, this path is
insilmaril@28
   609
converted to a relative one (e.g. {\tt /home/user/vym.map} might become
insilmaril@28
   610
{\tt ./vym.map}. This makes it fairly easy to use multiple maps on
insilmaril@28
   611
different computers or export them to HTML in future.
insilmaril@28
   612
insilmaril@28
   613
\subsection{Multiple maps} \label{tabs}
insilmaril@28
   614
You can work on multiple maps at the same time. Each new map is opened
insilmaril@28
   615
in another {\em tab}. The available tabs are shown just above the
insilmaril@28
   616
mapeditor. You can use the normal cut/copy/paste functions to
insilmaril@28
   617
copy data from one map to another.
insilmaril@28
   618
insilmaril@28
   619
%todo
insilmaril@28
   620
insilmaril@28
   621
%TODO
insilmaril@28
   622
%\subsubsection{Menus}
insilmaril@28
   623
%\subsubsection{Keyboard shortcuts}
insilmaril@28
   624
insilmaril@28
   625
% Settings
insilmaril@28
   626
% Images
insilmaril@28
   627
% Copy & Paste
insilmaril@28
   628
% Working with tabs (multiple maps)
insilmaril@28
   629
% Exporting
insilmaril@28
   630
% Scrolling
insilmaril@28
   631
insilmaril@28
   632
\section{Noteeditor} \label {noteeditor}
insilmaril@486
   633
If you want to attach more text to a branch e.g. a complete email, a
insilmaril@28
   634
cooking recipe, or the whole source code of a software project, you can
insilmaril@125
   635
use the noteeditor. 
insilmaril@509
   636
	\maximage{images/noteeditor.png}
insilmaril@486
   637
This editor displays text associated with a branch selected in the mapeditor. The noteeditor
insilmaril@486
   638
shows different background colours depending on whether text is associated with a selected branch.
insilmaril@28
   639
insilmaril@125
   640
\subsection{States}
insilmaril@28
   641
Before you can type or paste text into it, you have
insilmaril@486
   642
to select a branch in the mapeditor. Note that the background colour
insilmaril@28
   643
of the noteeditor indicates its state:
insilmaril@28
   644
\begin{itemize}
insilmaril@28
   645
	\item grey: no text entered yet
insilmaril@486
   646
	\item white: some text has been entered
insilmaril@28
   647
\end{itemize}	
insilmaril@486
   648
In the mapeditor itself, to signal that there is a note with more
insilmaril@486
   649
information for a particular branch, a little "note" flag will appear next
insilmaril@486
   650
to the heading of the branch. This is illustrated in the lower branch on the right hand side:
insilmaril@509
   651
	\maximage{images/branches-flags.png}
insilmaril@28
   652
insilmaril@125
   653
\subsection{Import and export notes}
insilmaril@420
   654
The note is always saved automatically within the \vym map itself.
insilmaril@28
   655
Nevertheless sometimes it is nice to import a note from an external file
insilmaril@486
   656
or write it. In the Note Editor use "File\ra~Import" and "File\ra~Export" to do so. 
insilmaril@28
   657
insilmaril@125
   658
\subsection{Edit and print note}
insilmaril@28
   659
Editing works like in any simple texteditor, including undo and redo
insilmaril@28
   660
functions. You can delete the complete note by clicking the
insilmaril@28
   661
trashcan. Only the note itself is printed by clicking the printer icon.
insilmaril@28
   662
insilmaril@486
   663
\subsection{RichText: Colours, paragraphs and formatted text}
insilmaril@233
   664
\vym supports formatted text (QT Rich Text) in the noteeditor since
insilmaril@486
   665
version 1.4.7.  Colours and text attributes (e.g. italic, bold) can be
insilmaril@486
   666
set with the buttons above the text.  The text itself is divided into
insilmaril@233
   667
paragraphs. For each paragraph the format can be set (e.g. centered,
insilmaril@233
   668
right). A paragraph is ended when a \key{Return} is entered. If you just
insilmaril@233
   669
want to begin a new line, press \key{CTRL-Return}.
insilmaril@233
   670
insilmaril@486
   671
\subsection{Fonts and how to switch them quickly}
insilmaril@486
   672
The noteeditor is designed to be used for simple notes, not really as a full
insilmaril@493
   673
featured word processor. Because of many requests \vym supports 
insilmaril@28
   674
formatted text in the noteeditor\footnote{
insilmaril@28
   675
	\vym uses the QRichtText format, which is basically a subset of the
insilmaril@28
   676
	formatting provided in HTML.}
insilmaril@544
   677
Two default fonts are supported which can be set in the Settings menu
insilmaril@544
   678
(see \ref{settings}).
insilmaril@28
   679
One is a fixed width font, the other has variable width. The fixed font
insilmaril@28
   680
is usually used for emails, source code etc.\ while the variable font is
insilmaril@28
   681
used for simple notes, where one doesn't need fixed character widths.
insilmaril@28
   682
Both fonts can easily switched using the following symbol from the
insilmaril@28
   683
toolbar:
insilmaril@28
   684
\begin{center}
insilmaril@450
   685
	\includegraphics[width=0.5cm]{images/formatfixedfont.png}
insilmaril@28
   686
\end{center}
insilmaril@486
   687
In the Settings menu both fonts can be set. The default font can also be toggled between the fixed and variable font by selecting or deselecting the "fixed font is default" menu item.
insilmaril@28
   688
insilmaril@28
   689
Additionally to the default fonts any font installed on your system can
insilmaril@28
   690
be used. Please note, that the chosen font also will be used for HTML
insilmaril@486
   691
exports, so if youy VYM mind map could ever be exported to a web or intranet page you should only use fonts which are available generally.
insilmaril@28
   692
insilmaril@217
   693
\subsection{Find text}
insilmaril@28
   694
The noteeditor itself has no Find function, use Find in the mapeditor,
insilmaril@28
   695
which will also search all notes (see \ref{findwindow}).
insilmaril@28
   696
insilmaril@217
   697
\subsection{Paste text into note editor}
insilmaril@28
   698
Often you will paste text into the editor from another application e.g.
insilmaril@28
   699
an email. Normally \vym will generate a new paragraph for each new line.
insilmaril@28
   700
This usually is not what you want, so you can choose from the menu
insilmaril@28
   701
insilmaril@493
   702
insilmaril@28
   703
\section{Hello world}
insilmaril@233
   704
This section is about how \vym can interact with other applications.
insilmaril@486
   705
Many applications can now read and write their data using XML, the
insilmaril@233
   706
eXtensible Markup Language. \vym also uses XML to save its maps, see
insilmaril@233
   707
\ref{fileformat} for a more detailed description. 
insilmaril@233
   708
insilmaril@486
   709
So if you make use of another application that understands XML, chances are good that someone
insilmaril@233
   710
could write import/export filters for \vym. Volunteers are always
insilmaril@233
   711
welcome ;-)
insilmaril@233
   712
insilmaril@340
   713
\subsection{Import} \label{import}
insilmaril@233
   714
insilmaril@233
   715
\subsubsection*{KDE Bookmarks}
insilmaril@486
   716
The integrated bookmark editor in KDE (Konqueror etc.) is somewhat limited, so why not
insilmaril@233
   717
use \vym to maintain the bookmark mess? To create a new map containing
insilmaril@233
   718
your current KDE bookmarks just choose
insilmaril@233
   719
\begin{itemize}
insilmaril@486
   720
	\item File \ra Import\ra KDE Bookmarks
insilmaril@233
   721
\end{itemize}
insilmaril@233
   722
insilmaril@233
   723
\subsubsection*{Mind Manager}
insilmaril@233
   724
\vym has currently a very basic import filter to convert maps created by
insilmaril@486
   725
{\em Mind Manager}\footnote{Mind Manager is a commercial i.e. non free, software application by Mindjet for Windows and the Mac. Both names are registered trademarks by Mindjet. For more information see their website at
insilmaril@486
   726
\href{http://mindjet.com}{http://mindjet.com}} into \vym maps. Notes and
insilmaril@233
   727
pictures are not converted at the moment. You can import files with
insilmaril@233
   728
\begin{itemize}
insilmaril@486
   729
	\item File \ra Import\ra Mind Manager
insilmaril@233
   730
\end{itemize}
insilmaril@233
   731
insilmaril@233
   732
insilmaril@233
   733
\subsubsection*{Directory structure}
insilmaril@233
   734
\vym can read a directory structure. This is mainly for
insilmaril@233
   735
testing \vym e.g. to easily create huge maps used for benchmarks (yes,
insilmaril@233
   736
there is still room to optimize \vym ;-)
insilmaril@28
   737
insilmaril@340
   738
insilmaril@340
   739
insilmaril@340
   740
insilmaril@340
   741
\subsection{Export}  \label{export}
insilmaril@264
   742
\label{hideexport}
insilmaril@486
   743
Often you may not want to export the whole map, but just parts of it. For
insilmaril@264
   744
example you may have additional info you want to talk about in a
insilmaril@264
   745
presentation, while those parts should not be visible to the audience.
insilmaril@264
   746
To achieve this you can "hide" parts of the map during exports by
insilmaril@291
   747
setting the "hide in export" flag.
insilmaril@264
   748
\begin{center}
insilmaril@450
   749
	\includegraphics[width=0.5cm]{images/flag-hideexport.png}
insilmaril@264
   750
\end{center}
insilmaril@291
   751
You can toggle this flag in the toolbar or by pressing \key{H}.
insilmaril@544
   752
Note that there is a global option in the settings menu (
insilmaril@544
   753
\ref{settings}) to toggle the use of this flag. By default the flag is
insilmaril@544
   754
enabled.
insilmaril@233
   755
insilmaril@233
   756
\subsubsection*{Open Office}
insilmaril@486
   757
Open Office beginning with version~2 uses the so called "Open Document Format", which can be written by \vym. The options are
insilmaril@233
   758
currently limited, but it possible to export presentations which can be
insilmaril@233
   759
opened in Open Office Impress. By selecting
insilmaril@28
   760
\begin{itemize}
insilmaril@486
   761
	\item File  \ra Export\ra Open Office
insilmaril@28
   762
\end{itemize}
insilmaril@233
   763
you get a file dialogue where you can choose the output file and the
insilmaril@233
   764
file type:
insilmaril@509
   765
	\maximage{images/export-oo.png}
insilmaril@233
   766
The file types represent various templates, which can be created with
insilmaril@233
   767
some manual work from an existing Open Office document. The structure of
insilmaril@233
   768
\vym map is then inserted into a template. 
insilmaril@233
   769
There are some limitations at the moment:
insilmaril@233
   770
\begin{itemize}
insilmaril@233
   771
	\item \vym can't take care of page lengths, so you have to check and
insilmaril@233
   772
	probably reedit in Open Office to avoid text running over the end of
insilmaril@233
   773
	a page
insilmaril@233
   774
	\item Images and flags are not used at the moment
insilmaril@486
   775
	\item Notes are just written as plain text, without RichText 
insilmaril@486
   776
	\item The full range of templates are not available in all distributions.	
insilmaril@233
   777
\end{itemize}
insilmaril@486
   778
Some of the templates make use of {\em sections} i.e sections insert the
insilmaril@233
   779
headings of mainbranches as chapters for sections into the presentation.
insilmaril@28
   780
insilmaril@28
   781
\subsubsection*{Image}
insilmaril@28
   782
\vym supports all image formats which are natively supported by the
insilmaril@28
   783
QT~toolkit:
insilmaril@28
   784
BMP, JPEG, PBM, PGM, PNG, PPN, XPM, and XBM.
insilmaril@28
   785
For use in websites and for sending images by email PNG is a good
insilmaril@28
   786
recommodation regarding quality and size of the image. \vym uses QTs
insilmaril@28
   787
default options for compressing the images.
insilmaril@28
   788
insilmaril@28
   789
\subsubsection*{ASCII}
insilmaril@28
   790
Exporting an image as text is somewhat experimental at the moment. Later
insilmaril@486
   791
this will probably be done using stylesheets. So the output may change in
insilmaril@28
   792
future versions of \vym.
insilmaril@28
   793
insilmaril@233
   794
\subsubsection*{\LaTeX}
insilmaril@233
   795
\vym can generate an input file for \LaTeX. Currently this is considered
insilmaril@233
   796
as experimental, there are no options (yet). 
insilmaril@233
   797
By selecting
insilmaril@233
   798
\begin{itemize}
insilmaril@486
   799
	\item File  \ra Export\ra \LaTeX 
insilmaril@233
   800
\end{itemize}
insilmaril@233
   801
you will be asked in a file dialog for the name of the output file. This
insilmaril@486
   802
file may then be included in a \LaTeX document using command: 
insilmaril@233
   803
\begin{verbatim}
insilmaril@233
   804
	\include{inputfile.tex}
insilmaril@233
   805
\end{verbatim}
insilmaril@233
   806
insilmaril@340
   807
\subsubsection*{KDE Bookmarks}
insilmaril@340
   808
\vym will overwrite the KDE bookmarks file and then try to notify
insilmaril@486
   809
running Konquerors via DCOP of the changed file. \vym does not create a
insilmaril@340
   810
backup!
insilmaril@340
   811
\begin{itemize}
insilmaril@486
   812
	\item File \ra Export \ra KDE Bookmarks
insilmaril@340
   813
\end{itemize}
insilmaril@340
   814
insilmaril@340
   815
insilmaril@233
   816
\subsubsection*{XHTML (Webpages)}
insilmaril@233
   817
insilmaril@486
   818
This is the format to use if you wish to create a webpage. To see an example
insilmaril@486
   819
visit the \vym homepage: 
insilmaril@233
   820
\href{http://www.InSilmaril.de/vym}{www.InSilmaril.de/vym}
insilmaril@233
   821
insilmaril@486
   822
Some explanation on how this works: 
insilmaril@233
   823
Before a map is exported as XHTML, it will be first written as XML into a
insilmaril@28
   824
directory (see \ref{xmlexport}). Then the external program {\tt
insilmaril@486
   825
xsltproc}\footnote{On SUSE Linux and some other distributions {\tt xsltproc} is installed by
insilmaril@28
   826
default.}
insilmaril@28
   827
will be called to process the XML file and generate HTML code.
insilmaril@486
   828
A dialog allows the user to set various options:
insilmaril@28
   829
\begin{itemize}
insilmaril@28
   830
	\item {\bf Include image:} If set, \vym will creat an image map at
insilmaril@28
   831
	the top of the HTML output. Clicking on a branch in the map will
insilmaril@28
   832
	jump to the corresponding section in the output.
insilmaril@28
   833
insilmaril@28
   834
	\item {\bf Colored headings:}
insilmaril@486
   835
	If set to yes, \vym will colour the headings in the text part  with the
insilmaril@486
   836
	same colours used in the \vym map.
insilmaril@28
   837
	\item {\bf Show Warnings:}
insilmaril@28
   838
	If set to yes, \vym will ask before overwriting data.
insilmaril@28
   839
	\item {\bf Show output:}
insilmaril@28
   840
	This is useful mainly for debugging. It will show how the processing of
insilmaril@28
   841
	the XML file works by calling the external {\tt xsltproc}.
insilmaril@28
   842
\end{itemize}
insilmaril@28
   843
Additionally the paths to the CSS and XSL stylesheets can be set. By
insilmaril@28
   844
default on SUSE~Linux they will be in {\tt /usr/share/vym/styles}.
insilmaril@28
   845
insilmaril@28
   846
insilmaril@28
   847
\subsubsection*{XML} \label{xmlexport}
insilmaril@486
   848
The map is written into a directory both as an image and as an XML file. The
insilmaril@28
   849
directory is set in a file dialog. If the directory is not empty, you
insilmaril@486
   850
will be warned and offered choices if you are at risk of overwriting existing contents.
insilmaril@28
   851
insilmaril@28
   852
It is possible to export different maps into the same directory. Each
insilmaril@28
   853
file generated will have the map's name as prefix, e.g. {\tt todo.vym}
insilmaril@28
   854
becomes {\tt todo.xml}, {\tt todo.png}, {\tt todo-image-1.png} and so
insilmaril@486
   855
on. This is useful if, for example, a website comprises several combined maps that have to be stored in the same directory.
insilmaril@28
   856
insilmaril@105
   857
\subsubsection*{Export a part of a map}
insilmaril@486
   858
Select a branch you want to export together with its children, then open
insilmaril@105
   859
the context menu and choose {\em Save Selection}. This will create a
insilmaril@486
   860
file with the suffix {\tt .vyp}, which is an abbreviation for \lq vym
insilmaril@105
   861
part\rq.
insilmaril@105
   862
insilmaril@125
   863
insilmaril@125
   864
\section{Advanced Editing}
insilmaril@340
   865
insilmaril@493
   866
\subsection{Properties of an object} 
insilmaril@493
   867
For any branch you can open a satellite window (see \ref{satellite}):
insilmaril@493
   868
the {\em property window}:
insilmaril@493
   869
\begin{center}
insilmaril@493
   870
	\includegraphics[width=8cm]{images/propwindow.png}
insilmaril@493
   871
	\label{propwindow}
insilmaril@493
   872
\end{center}
insilmaril@493
   873
%FIXME create screenshot
insilmaril@493
   874
%FIXME explain the tabs
insilmaril@493
   875
insilmaril@493
   876
\begin{itemize}
insilmaril@493
   877
	\item Frame
insilmaril@493
   878
	\item Link (see \ref{hideunselected})
insilmaril@493
   879
	\item Layout (see \ref{incimg})
insilmaril@493
   880
\end{itemize}
insilmaril@493
   881
insilmaril@420
   882
\subsection{Changing the history: Undo and Redo}
insilmaril@493
   883
\vym keeps track of all changes done in a map. The default number of
insilmaril@493
   884
changes which can be undone is~75. The complete history can be seen in
insilmaril@493
   885
the {\em historywindow}:
insilmaril@509
   886
	\maximage{images/historywindow.png}
insilmaril@493
   887
	\label{historywindow}
insilmaril@493
   888
A single step back be undone or redone with \key{CTRL-Z} or \key{CTRL-Y},
insilmaril@493
   889
or by using the buttons in the toolbar or the {\em historywindow}.
insilmaril@493
   890
Inside the {\em historywindow}, you can click on a line to unwind all
insilmaril@493
   891
actions done until that point in time -- or redo all changes by clicking
insilmaril@493
   892
on the last line.
insilmaril@420
   893
insilmaril@509
   894
\hint{
insilmaril@509
   895
	You can "paste from the past": Go back in time by e.g. with
insilmaril@509
   896
	\key{CTRL-Z}, then copy to clipboard by pressing \key{CTRL-C}.
insilmaril@509
   897
insilmaril@509
   898
	Now do all actions again, e.g. by \key{CTRL-Y} or clicking on the
insilmaril@509
   899
	last action in {\em historywindow}. Now paste from the past with
insilmaril@509
   900
	\key{CTRL-V}.
insilmaril@509
   901
}
insilmaril@509
   902
insilmaril@450
   903
\subsection{Macros} \label{macros}
insilmaril@527
   904
Macros have been added to \vym in version~1.9.0. 
insilmaril@527
   905
So far they have a preliminary character, maybe they are going to be
insilmaril@527
   906
replaced by full-featured scripting functionality later (though the
insilmaril@527
   907
commands will be more or less the same).
insilmaril@527
   908
insilmaril@527
   909
Each function key
insilmaril@450
   910
\key{F1} to \key{F12} holds a macro, which is executed on the current
insilmaril@486
   911
selection if the key is pressed. The default macros change the colour of
insilmaril@450
   912
a subtree or set the frame of a branch:
insilmaril@450
   913
\begin{center}
insilmaril@450
   914
	\includegraphics[width=8cm]{images/macros.png}
insilmaril@450
   915
\end{center}
insilmaril@450
   916
Each macro is a \vym script, which is executed when the associated key
insilmaril@450
   917
is pressed. The default location of the scripts can be changed in the
insilmaril@450
   918
Settings menu. More information on using scripts in \vym is found in
insilmaril@544
   919
[\ref{settings})
insilmaril@450
   920
appendix~\ref{scripts}.
insilmaril@450
   921
insilmaril@493
   922
\subsection{Bookmarks} \label{bookmarks}
insilmaril@340
   923
\subsubsection*{Open new tabs instead of new windows}
insilmaril@486
   924
If you use konqueror as your browser, \vym will remember the konqueror session which
insilmaril@340
   925
was opened first by \vym. You can also press \key{Ctrl} and click to
insilmaril@486
   926
open the link in a new tab.
insilmaril@340
   927
insilmaril@340
   928
\vym can also open a new tab in Mozilla or Firefox using the remote
insilmaril@340
   929
command\footnote{\href{http://www.mozilla.org/unix/remote.html}{http://www.mozilla.org/unix/remote.html}}
insilmaril@486
   930
of these browsers.
insilmaril@340
   931
insilmaril@340
   932
\subsubsection*{Drag and Drop}
insilmaril@340
   933
If you want to keep bookmarks in a map, select a branch where you want
insilmaril@340
   934
to add the bookmark, then simply drag the URL from your browser to the
insilmaril@340
   935
map. Also you could use an existing heading as URL: Right click onto the
insilmaril@340
   936
branch and select "Use heading for URL".
insilmaril@340
   937
insilmaril@340
   938
insilmaril@340
   939
\subsubsection*{Directly access bookmark lists of a browser}
insilmaril@340
   940
Please see the sections \ref{import} and \ref{export} about
insilmaril@340
   941
Import and Export filters.
insilmaril@340
   942
insilmaril@340
   943
\subsubsection*{Special URLs}
insilmaril@340
   944
\vym can turn an existing heading of a branch into an URL. Currently
insilmaril@340
   945
this works for Bugentries in the Novell Bugtracking system: Open the
insilmaril@340
   946
context menu of a branch (usually by right-clicking it) and select
insilmaril@340
   947
\begin{itemize}
insilmaril@340
   948
	\item Create URL to Bugzilla
insilmaril@340
   949
\end{itemize}
insilmaril@340
   950
The URL will be build from the number in the heading.
insilmaril@340
   951
insilmaril@493
   952
\subsection{Associating images with a branch} \label{incimg}
insilmaril@486
   953
The default setting for an image is for it to float "freely". Images can be
insilmaril@486
   954
positioned anywhere on the canvas, but may end up in the same place as other
insilmaril@486
   955
parts of the map obscuring that part of the map.
insilmaril@340
   956
insilmaril@486
   957
The solution is to insert or include them "into" a branch. This can be done via
insilmaril@493
   958
the property window (see \ref{propwindow}):
insilmaril@340
   959
\begin{itemize}
insilmaril@340
   960
	\item Include images horizontally
insilmaril@340
   961
	\item Include images vertically
insilmaril@340
   962
\end{itemize}
insilmaril@486
   963
The image is still positioned relative to its parent branch, but the
insilmaril@486
   964
heading and border of the branch frame adapt to the floating image, see below: 
insilmaril@509
   965
	\maximage{images/includeImages.png}
insilmaril@340
   966
insilmaril@125
   967
\subsection{Modifier Modes} 
insilmaril@486
   968
Modifiers are for example the \key{Shift}- the \key{Ctrl}- ot the \key{Alt}-keys. When
insilmaril@486
   969
pressed while applying mouse actions, they will cause \vym to use
insilmaril@493
   970
a "modified" version of the action which usually would be done. 
insilmaril@493
   971
insilmaril@493
   972
%\key{Ctrl} or \key{Alt}is pressed while releasing the branch, it will be
insilmaril@493
   973
%added above/below the target, not as child of the target.
insilmaril@125
   974
insilmaril@486
   975
Without a modifier key pressed, the first mouse click on a branch just selects
insilmaril@125
   976
it. For the behaviour of the \key{Ctrl} modifier there are several
insilmaril@125
   977
options, which can be set from the modifier toolbar:
insilmaril@125
   978
\begin{center}
insilmaril@450
   979
	\includegraphics[width=3cm]{images/modmodes.png}
insilmaril@125
   980
\end{center}
insilmaril@493
   981
The default mode is to copy the colour from the clicked branch to the already
insilmaril@493
   982
selected branch. The figure above shows the toolbar with the default modifier 
insilmaril@493
   983
selected. The second modifier
insilmaril@125
   984
let's you easily copy a whole branch with a single click. The third
insilmaril@493
   985
modifier lets you create links between branches called {\em xLinks}.
insilmaril@493
   986
They will be explained in the next section \ref{xlinks}.
insilmaril@125
   987
insilmaril@493
   988
\subsection{Hide links of unselected objects} \label{hidelink}
insilmaril@264
   989
Sometimes it would be useful to position a branch freely, just like a
insilmaril@486
   990
mainbranch or an image. This is possible for all
insilmaril@264
   991
branches, you can use a mainbranch and hide its connecting link to the
insilmaril@486
   992
mapcenter or hide the link between a child branch and its parent. This can be used e.g. for legends or a collection of vymLinks
insilmaril@264
   993
pointing to other maps:
insilmaril@264
   994
\begin{center}
insilmaril@450
   995
	\includegraphics[width=9cm]{images/hiddenlink.png}
insilmaril@264
   996
\end{center}
insilmaril@493
   997
To hide the link between a branch and its parent open the
insilmaril@493
   998
\ref{propwindow} and check "Hide link if object is not selected" on
insilmaril@493
   999
"Link" tab.
insilmaril@264
  1000
insilmaril@264
  1001
insilmaril@260
  1002
\subsection{XLinks} \label{xlinks}
insilmaril@125
  1003
So far all the data in the \vym map has been treelike. Using xLinks you
insilmaril@125
  1004
can link one branch to any other, just like attaching a rope between two
insilmaril@125
  1005
branches in a real tree. This is especially useful in complex maps,
insilmaril@486
  1006
where you want to have crossreferences which can not be displayed on the same
insilmaril@486
  1007
visible area of the {\em mapeditor} window. The following example map 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:
insilmaril@509
  1008
	\maximage{images/xlink.png}
insilmaril@125
  1009
Note that a xLink which points to a branch that is not visible (because
insilmaril@486
  1010
it is scrolled), is just shown as a little horizontal arrow. In the
insilmaril@125
  1011
screenshot above have a look at the \lq Tuesday\rq\ branch.
insilmaril@125
  1012
insilmaril@233
  1013
\subsubsection*{Create a xLink}
insilmaril@486
  1014
Choose the link mode from the modifier toolbar (by clicking the toolbar icon or pressing
insilmaril@125
  1015
\key{L}). Select the branch, where the xLink should start. Press the
insilmaril@486
  1016
modifier key \key{Ctrl} and then click on the selected branch where the
insilmaril@486
  1017
link should start and drag the mouse pointer to the branch where the link is to end. (The link is drawn to follow the mouse pointer). When you release the mouse over a branch the xLink becomes permanent.
insilmaril@125
  1018
insilmaril@233
  1019
\subsubsection*{Modify or delete a xLink}
insilmaril@493
  1020
First select a branch at either end of the xLink. Then open the context
insilmaril@493
  1021
menu and select \lq Edit xLink\rq. A submenu contains all the xLinks of
insilmaril@493
  1022
the branch (if there are any). They are named like the branches, where
insilmaril@493
  1023
they end. Choose one and the xLink dialogue opens, where you can set
insilmaril@493
  1024
colour, width and also delete the xLink.
insilmaril@125
  1025
insilmaril@233
  1026
\subsubsection*{Follow a xLink}
insilmaril@486
  1027
In a complex \vym map it sometimes comes in handy to be able to jump to the other end
insilmaril@493
  1028
of a xLink. You can do this by opening the context menu of the branch
insilmaril@493
  1029
and clicking on \lq Goto xLink\rq and selecting the xLink you want to
insilmaril@493
  1030
follow.
insilmaril@125
  1031
insilmaril@125
  1032
insilmaril@125
  1033
insilmaril@233
  1034
\subsection{Adding and removing branches}
insilmaril@125
  1035
The context menu of a branch shows some more ways to add and delete data
insilmaril@486
  1036
e.g. you can delete a branch while keeping its children. The children become
insilmaril@125
  1037
linked to the parent of the previously removed branch.
insilmaril@125
  1038
Similar branches can be inserted into existing maps. For keyboard
insilmaril@125
  1039
shortcuts also have a look at the context menu.
insilmaril@28
  1040
insilmaril@233
  1041
\subsection{Adding a whole map or a part of a map}
insilmaril@493
  1042
Select a branch where you want to add a previously saved map ({\tt
insilmaril@493
  1043
.vym})or a part of a map ({\tt .vyp}) , then open the context menu and
insilmaril@493
  1044
choose {\em Add \ra Add Map (Insert)}. For the import you can choose
insilmaril@493
  1045
between {\em Add Map (Insert)} and {\em Add Map (Replace)}: The imported
insilmaril@493
  1046
data will be added after the selected branch.
insilmaril@105
  1047
insilmaril@544
  1048
insilmaril@105
  1049
\section{\vym on Mac OS X}
insilmaril@105
  1050
\subsection{Overview}
insilmaril@105
  1051
Basically there are two ways to run \vym on Macs:
insilmaril@544
  1052
\subsubsection*{Qt Mac Edition:}
insilmaril@105
  1053
	\vym here provides the well known Mac look and feel.  \vym is
insilmaril@544
  1054
	available as Mac OS X application package in contained in a disk
insilmaril@544
  1055
	image ({\tt vym.dmg}. It has been compiled and tested in
insilmaril@544
  1056
	Mac~OS~10.4.  This package includes  runtime libraries of Qt by
insilmaril@544
  1057
	Trolltech.
insilmaril@544
  1058
	
insilmaril@544
  1059
\subsubsection*{X11 version} \vym can also be run using the Linux
insilmaril@544
  1060
version, but then menus and handling will also be those of the Linux
insilmaril@544
  1061
version e.g. The menu bar will look different. 
insilmaril@105
  1062
insilmaril@125
  1063
\subsection	{Contextmenu and special keys}
insilmaril@125
  1064
Most Macs unfortunatly just have a single mouse button. In order to show
insilmaril@125
  1065
the context menu which usually would be opened with the right mouse
insilmaril@544
  1066
button, you can click while pressing the \key{command}-key.
insilmaril@125
  1067
insilmaril@125
  1068
Especially on Laptops some of the keys usually used on PC keyboards seem
insilmaril@125
  1069
to be missing. The QT-Mac Edition of \vym has its own keyboard
insilmaril@125
  1070
shortcuts. To find the shortcuts just have a look at all the menu
insilmaril@125
  1071
entries, the shortcut is visible next to an entry. Toolbar buttons also
insilmaril@125
  1072
may have shortcuts, just position the mouse pointer over a button and
insilmaril@125
  1073
wait for the little help window to appear. 
insilmaril@125
  1074
insilmaril@125
  1075
\subsection {Viewing external links}
insilmaril@125
  1076
\vym on Mac uses the system call {\tt /usr/bin/open} to view links.
insilmaril@125
  1077
Mac~OS determines automatically if the link is a pdf or www page and
insilmaril@125
  1078
opens the right browser.
insilmaril@125
  1079
insilmaril@233
  1080
insilmaril@544
  1081
\newpage
insilmaril@544
  1082
insilmaril@233
  1083
\begin{appendix}
insilmaril@233
  1084
insilmaril@486
  1085
\section{\vym initialisation process and configuration}
insilmaril@544
  1086
\subsection {Settings menu}
insilmaril@544
  1087
	The {\em Settings} menu allows to configure \vym to your needs:
insilmaril@544
  1088
insilmaril@544
  1089
\subsubsection*{Set application to open PDF files} Choose a PDF
insilmaril@544
  1090
	viewer like {\tt acrobat} or {\tt konqueror} which is installed on
insilmaril@544
  1091
	your system.
insilmaril@544
  1092
insilmaril@544
  1093
\subsubsection*{Set application to open external links}
insilmaril@544
  1094
	Choose your favourite webbrowser here.
insilmaril@544
  1095
insilmaril@544
  1096
\subsubsection*{Set path for macros}
insilmaril@544
  1097
	Set the default search path for macros, which will be executed when
insilmaril@544
  1098
	you press one of the function keys. Each key corresponds to a file
insilmaril@544
  1099
	({\tt macro-1.vys..macro12.vys}) in the search path.
insilmaril@544
  1100
insilmaril@544
  1101
\subsubsection*{Set number of undo levels}
insilmaril@544
  1102
	Sets the number of undo/redo levels. The default setting is
insilmaril@544
  1103
	75~levels.
insilmaril@544
  1104
insilmaril@544
  1105
\subsubsection*{Autosave and autosave time}
insilmaril@544
  1106
	Automatic saving of modified maps can be toggled on or off. The
insilmaril@544
  1107
	autosave time is entered in seconds.
insilmaril@544
  1108
insilmaril@544
  1109
\subsubsection*{Edit branch after adding it}
insilmaril@544
  1110
	If set, the heading of a new branch will be edited immediatly after
insilmaril@544
  1111
	adding the branch.
insilmaril@544
  1112
insilmaril@544
  1113
\subsubsection*{Select branch after adding it}
insilmaril@544
  1114
	If set, a new branch will be selected immediatly after adding it.
insilmaril@544
  1115
	When you "brainstorm" on a given keyword, you don't want to go
insilmaril@544
  1116
	deeper and deeper into details, but keep the focus on the keyword.
insilmaril@544
  1117
	So the default setting here is to {\em not} select the freshly added
insilmaril@544
  1118
	branch.
insilmaril@544
  1119
	
insilmaril@544
  1120
\subsubsection*{Select existing heading}
insilmaril@544
  1121
	If set and you begin to edit the heading of a branch, the heading text in
insilmaril@544
  1122
	the dialog will be selected. Usefully to copy\&paste to other
insilmaril@544
  1123
	applications.
insilmaril@544
  1124
insilmaril@544
  1125
\subsubsection*{Delete key}
insilmaril@544
  1126
	If set, the \key{Delete} is enabled to, well, delete objects. This
insilmaril@544
  1127
	can be switched off to avoid confusing with the nearby
insilmaril@544
  1128
	\key{Insert}-key on PC keyboards.
insilmaril@544
  1129
insilmaril@544
  1130
\subsubsection*{Exclusive flags}
insilmaril@544
  1131
	If set, some of the standard flags can only be used exclusively,
insilmaril@544
  1132
	e.g.~the smileys.
insilmaril@544
  1133
insilmaril@544
  1134
\subsubsection*{Use hide flags}
insilmaril@544
  1135
	If set, every branch which also has the hide flag set (see
insilmaril@544
  1136
	\ref{hideexport}) will be hidden in exports.
insilmaril@420
  1137
\subsection{Configuration file}
insilmaril@420
  1138
On startup \vym will look for a configuration for user specific settings
insilmaril@420
  1139
like window positions, toolbars etc. If this file does not already
insilmaril@420
  1140
exist, it will be created. The file is located in the users home
insilmaril@420
  1141
directory. The exact position depends on the platform:
insilmaril@420
  1142
\begin{center}
insilmaril@420
  1143
\begin{tabular}{cl}
insilmaril@420
  1144
	{\bf Platform}	& {\bf Configuration file} \\ \hline
insilmaril@420
  1145
	Linux		& {\tt $\sim$/.config/InSilmaril/vym.conf  } \\
insilmaril@420
  1146
	Mac OS X	& {\tt /Users/NAME/Library/Preferences/com.insilmaril.vym.plist  } \\
insilmaril@420
  1147
\end{tabular}
insilmaril@420
  1148
\end{center}
insilmaril@420
  1149
The file can be edited manually, or on Mac~OS~X with Property List
insilmaril@420
  1150
Editor (installed with xtools).
insilmaril@420
  1151
insilmaril@291
  1152
\subsection{Path to ressources}
insilmaril@291
  1153
\vym will try to find its ressources (images, stylesheets, filters,
insilmaril@291
  1154
etc.) in the following places:
insilmaril@291
  1155
\begin{enumerate}
insilmaril@291
  1156
	\item Path given by the environment variable {\tt VYMHOME}.
insilmaril@291
  1157
	\item If called with the local option (see \ref{options} below),
insilmaril@291
  1158
	      \vym will look for its data in the current directory.
insilmaril@291
  1159
	\item {\tt /usr/share/vym}
insilmaril@291
  1160
	\item {\tt /usr/local/share/vym}
insilmaril@291
  1161
\end{enumerate}
insilmaril@291
  1162
insilmaril@291
  1163
\subsection{Command line options} \label{options}
insilmaril@264
  1164
\vym has the following options:
insilmaril@264
  1165
\begin{center}
insilmaril@450
  1166
\begin{tabular}{cccp{8cm}}\\ 
insilmaril@450
  1167
\bf Option	& \bf Comment & \bf Argument & \bf Description \\ \hline
insilmaril@493
  1168
v & version &			& Show version and codename of \vym\\
insilmaril@450
  1169
l & local	&			& Use local paths to stylesheets, translations, icons, 
insilmaril@450
  1170
                          etc. instead of system paths. Useful for testing\\
insilmaril@486
  1171
h & help	&			& Show help\\
insilmaril@519
  1172
r & run 	& filename	& Load and run script\\
insilmaril@479
  1173
q & quit	&			& Quit immediatly after startup. Useful for benchmarks.\\
insilmaril@264
  1174
\end{tabular}
insilmaril@264
  1175
\end{center}
insilmaril@264
  1176
You can also give several filenames at the commandline to let \vym open
insilmaril@264
  1177
several maps at once.
insilmaril@264
  1178
 
insilmaril@450
  1179
insilmaril@514
  1180
\section{Scripts} \label{scripts}   %FIXME
insilmaril@450
  1181
insilmaril@514
  1182
TODO: This section of the \vym manual is not complete yet, sorry.
insilmaril@450
  1183
insilmaril@514
  1184
\subsection{Example scripts}
insilmaril@514
  1185
\subsubsection{Export a set of maps}
insilmaril@514
  1186
\begin{code}
insilmaril@514
  1187
\# Simple vym script to export images of various maps simultanously
insilmaril@519
  1188
exportImage ();
insilmaril@514
  1189
\end{code}
insilmaril@514
  1190
The script above can be used to export all maps in a directory
insilmaril@514
  1191
automatically. If the script is named {\tt export-image.vys}, call \vym with
insilmaril@514
  1192
\begin{code}
insilmaril@514
  1193
\$ vym --quit --run export-image.vys *.vym
insilmaril@514
  1194
\end{code}
insilmaril@450
  1195
insilmaril@450
  1196
insilmaril@233
  1197
\section{Contributing to \vym}
insilmaril@260
  1198
So far I'd say I have written 98\% of the code on my own. No surprise,
insilmaril@260
  1199
that \vym exactly fits my own needs. Nevertheless I would like to
insilmaril@260
  1200
encourage all users of  \vym to contribute. Maybe not only with feature
insilmaril@260
  1201
requests, but also with code, new import/export filters, translations
insilmaril@260
  1202
etc. In this appendix I'll try to show how easy it is to expand the
insilmaril@260
  1203
things you can do already with \vym. I really look forward to hear from
insilmaril@260
  1204
you!
insilmaril@233
  1205
insilmaril@233
  1206
\subsection{Getting help}
insilmaril@233
  1207
insilmaril@233
  1208
\subsubsection*{Frequently asked questions}
insilmaril@233
  1209
Please refer to the FAQ available on the \vym website:
insilmaril@125
  1210
\begin{center}
insilmaril@125
  1211
\href{http://www.InSilmaril.de/vym/faq.html}{http://www.InSilmaril.de/vym/faq.html}
insilmaril@125
  1212
\end{center}
insilmaril@105
  1213
insilmaril@233
  1214
\subsubsection*{Mailinglists}
insilmaril@233
  1215
There are two mailinglists: {\tt vym-forum} is the \vym users forum to
insilmaril@233
  1216
discuss various questions, while {\tt vym-devel} is intended for people
insilmaril@233
  1217
interested in contributing to \vym. You can view the archives and
insilmaril@233
  1218
subscribe at
insilmaril@233
  1219
\begin{center}
insilmaril@233
  1220
\href{https://sourceforge.net/mail/?group_id=127802}{https://sourceforge.net/mail/?group\_id=127802}
insilmaril@233
  1221
\end{center}
insilmaril@233
  1222
insilmaril@264
  1223
\subsubsection*{Contacting the author}\label{author}
insilmaril@233
  1224
Especially for support questions please try the mailinglists first. If
insilmaril@486
  1225
everything else fails you can contact the author Uwe Drechsel at
insilmaril@233
  1226
\begin{center}
insilmaril@260
  1227
\href{mailto:vym@InSilmaril.de}{vym@InSilmaril.de}
insilmaril@233
  1228
\end{center}
insilmaril@233
  1229
insilmaril@233
  1230
insilmaril@264
  1231
insilmaril@264
  1232
\subsection{How to report bugs}
insilmaril@264
  1233
Though Sourceforge has its own bugreporting system, I'd rather prefer if
insilmaril@264
  1234
you contact me directly (see \ref{author}) or even better: You can file
insilmaril@264
  1235
a bugreport in Bugzilla, the bugtracking system of openSUSE:
insilmaril@264
  1236
\begin{center}
insilmaril@264
  1237
\href{http://en.opensuse.org/Submit_a_bug}{http://en.opensuse.org/Submit\_a\_bug}
insilmaril@264
  1238
\end{center}
insilmaril@264
  1239
I build \vym regulary for openSUSE, so you may report it against a
insilmaril@264
  1240
recent version there, even if you  use another Operating System.
insilmaril@486
  1241
Please don't forget to tell me what you are using:
insilmaril@264
  1242
\begin{itemize}
insilmaril@264
  1243
	\item the exact steps needed to reproduce the bug
insilmaril@264
  1244
	\item the version and build date of \vym (see the Help \ra About
insilmaril@264
  1245
	\vym)
insilmaril@264
  1246
	\item hardware and Operating System
insilmaril@264
  1247
\end{itemize}
insilmaril@264
  1248
insilmaril@233
  1249
\subsection{Compiling from the sources}
insilmaril@252
  1250
\subsubsection{Getting the sources} \label{getsources}
insilmaril@252
  1251
You find the latest version of \vym at the project site:
insilmaril@252
  1252
\begin{center}
insilmaril@252
  1253
\href{https://sourceforge.net/projects/vym/}{https://sourceforge.net/projects/vym/}
insilmaril@252
  1254
\end{center}
insilmaril@252
  1255
There you can check them out of the source repository (CVS):\\
insilmaril@233
  1256
insilmaril@252
  1257
\begin{verbatim}
insilmaril@252
  1258
cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/vym checkout code
insilmaril@252
  1259
\end{verbatim}
insilmaril@252
  1260
insilmaril@252
  1261
\subsubsection{The Qt toolkit}
insilmaril@233
  1262
Qt is C++ toolkit for multiplatform GUI and application development. It
insilmaril@233
  1263
provides single-source portability across MS~Windows, Mac~OS~X, Linux
insilmaril@486
  1264
and all major commercial Unix variants. Qt is also available for
insilmaril@252
  1265
embedded devices. Qt is a Trolltech product. For more information see 
insilmaril@252
  1266
\begin{center}
insilmaril@233
  1267
\href{http://www.trolltech.com/qt/}{www.trolltech.com/qt} 
insilmaril@252
  1268
\end{center}
insilmaril@233
  1269
insilmaril@233
  1270
insilmaril@252
  1271
\subsubsection{Compiling \vym }
insilmaril@233
  1272
Make sure you have installed your Qt environment properly, see the Qt
insilmaril@233
  1273
documentation for details. You need to have the Qt command {\tt qmake}
insilmaril@233
  1274
in your {\tt PATH}-environment, then run
insilmaril@514
  1275
\begin{code}
insilmaril@514
  1276
\$ qmake
insilmaril@514
  1277
$ make  
insilmaril@514
  1278
$ make install
insilmaril@514
  1279
\end{code}
insilmaril@233
  1280
The last command {\tt make install} needs root-permissions. Of course it
insilmaril@233
  1281
may be omitted, if you just want to test \vym.
insilmaril@233
  1282
insilmaril@260
  1283
%\subsubsection*{Compiling \vym on Macs}
insilmaril@450
  1284
%FIXME
insilmaril@233
  1285
insilmaril@233
  1286
\subsection{\vym file format} \label{fileformat}
insilmaril@486
  1287
\vym maps usually have the suffix "{\tt .vym}" and represent a
insilmaril@233
  1288
compressed archive of data. If you want to have a
insilmaril@233
  1289
closer look into the data structure map called "mapname.vym", 
insilmaril@233
  1290
just uncompress the map manually using
insilmaril@514
  1291
\begin{code}
insilmaril@514
  1292
\$ unzip mapname.vym
insilmaril@514
  1293
\end{code}
insilmaril@233
  1294
This will create directories named {\tt images} and {\tt flags} in your
insilmaril@233
  1295
current directory and also the map itself, usually named {\tt
insilmaril@233
  1296
mapname.xml}.
insilmaril@233
  1297
The XML structure of \vym is pretty self explaining, just have a look at
insilmaril@233
  1298
{\tt mapname.xml}.
insilmaril@233
  1299
insilmaril@233
  1300
This XML file can be loaded directly into \vym, it does not have to be
insilmaril@233
  1301
compressed. If you want to compress all the data yourself, use
insilmaril@514
  1302
\begin{code}
insilmaril@514
  1303
\$ zip -r mapname.vym .
insilmaril@514
  1304
\end{code}
insilmaril@233
  1305
to compress all data in your current directory.
insilmaril@233
  1306
insilmaril@233
  1307
\subsection{New features}
insilmaril@28
  1308
There are lots of features which might find their way into \vym.
insilmaril@233
  1309
Together with \vym you should have received a directory with several
insilmaril@514
  1310
example maps. You find them by clicking Help \ra Open~vym~example~maps.
insilmaril@514
  1311
There you will find the map {\tt vym-projectplan.vym}. It lists quite a
insilmaril@514
  1312
lot of things to be done in future. If you have more ideas, contact the
insilmaril@514
  1313
development team at {\tt vym-devel@lists.sourceforge.net}.
insilmaril@28
  1314
insilmaril@28
  1315
insilmaril@233
  1316
\subsection{New languages support}
insilmaril@252
  1317
In order to add a new language to \vym you need 
insilmaril@252
  1318
the sources (see \ref{getsources}) and
insilmaril@252
  1319
an installation of Trolltechs QT. A part of QT are the development
insilmaril@252
  1320
tools, from those tools especially the translation tool "Linguist" is
insilmaril@252
  1321
needed. 
insilmaril@252
  1322
insilmaril@252
  1323
In some Linux distributions the development tools are in an extra package, e.g. on SUSE LINUX you should have installed:
insilmaril@514
  1324
\begin{code}
insilmaril@514
  1325
libqt4-devel.rpm
insilmaril@514
  1326
libqt4-devel-doc.rpm
insilmaril@514
  1327
libqt4-devel-tools.rpm
insilmaril@514
  1328
\end{code}
insilmaril@252
  1329
If you don't have QT in your system, you can get it from 
insilmaril@252
  1330
	\href{http://www.trolltech.com}{http://www.trolltech.com} Once you
insilmaril@252
  1331
	are able to compile vym yourself, you can translate the text in vym
insilmaril@252
  1332
	itself by performing the following steps:
insilmaril@252
  1333
\begin{itemize}
insilmaril@252
  1334
	\item Let's assume now your encoding is "NEW" instead of for example
insilmaril@252
  1335
	"de" for german or "en" for english
insilmaril@252
  1336
	
insilmaril@252
  1337
	\item Copy the file {\tt lang/vym\_en.ts} to l{\tt ang/vym\_NEW.ts} (The code
insilmaril@252
  1338
	itself contains the english version.)
insilmaril@252
  1339
		
insilmaril@252
  1340
	\item Add {\tt lang/vym\_NEW.ts} to the TRANSLATIONS section of vym.pro
insilmaril@252
  1341
insilmaril@252
  1342
	\item Run Linguist on {\tt vym\_NEW.ts} and do the translation
insilmaril@252
  1343
insilmaril@252
  1344
	\item Run {\tt lrelease} to create {\tt vym\_NEW.qm}
insilmaril@252
  1345
insilmaril@252
  1346
	\item Do a make install to install the new vym and check your translation
insilmaril@252
  1347
\end{itemize}
insilmaril@252
  1348
insilmaril@252
  1349
If you feel brave, you can also translate the manual. It is written in
insilmaril@252
  1350
LaTeX, you just have to change the file tex/vym.tex. (Linguist and QT
insilmaril@252
  1351
are not needed, but it is useful to know how to work with LaTeX and esp.
insilmaril@252
  1352
pdflatex to create the PDF.) 
insilmaril@252
  1353
insilmaril@252
  1354
Please mail me every translation you have done. I can also give you a
insilmaril@252
  1355
developer access to the project, if you want to provide translations
insilmaril@252
  1356
regulary.  
insilmaril@252
  1357
insilmaril@233
  1358
\subsection{New export/import filters}
insilmaril@252
  1359
\vym supports various kinds of filters. Data can be written directly,
insilmaril@252
  1360
inserted into templates or it can be written as XML data and then
insilmaril@252
  1361
processed by XSL transformations. 
insilmaril@252
  1362
insilmaril@252
  1363
Most of the import/export functionality is available in the classes
insilmaril@252
  1364
ImportBase and ExportBase and subclasses. All of them can be found in
insilmaril@252
  1365
{\tt imports.h} and {\tt exports.h}.
insilmaril@252
  1366
insilmaril@264
  1367
\subsubsection*{Direct import/export}
insilmaril@252
  1368
An example for a direct export is the XML export. This method touches
insilmaril@252
  1369
the implementation of nearly every object of \vym, so whenever possible
insilmaril@264
  1370
you should better use a XSL transformation instead.
insilmaril@252
  1371
insilmaril@252
  1372
If you still want to know how it is done, start looking at 
insilmaril@252
  1373
{\tt MapEditor::saveToDir} in {\tt mapeditor.cpp}.
insilmaril@252
  1374
insilmaril@264
  1375
\subsubsection*{Templates}
insilmaril@264
  1376
Templates have been introduced to export to opendoc format used e.g. by
insilmaril@264
  1377
Open~Office. While I read the spec ($>$ 500 pages) about the format\footnote{
insilmaril@264
  1378
\href{http://www.oasis-open.org/}{http://www.oasis-open.org/}}\ 
insilmaril@264
  1379
I had the feeling that I did not want to write the export from scratch. 
insilmaril@264
  1380
It would be too complex to adapt the styles to your own wishes, e.g. the
insilmaril@264
  1381
layout.
insilmaril@252
  1382
insilmaril@264
  1383
Instead I analyzed existing Open~Office documents. I found out that
insilmaril@264
  1384
there are lots of redundant bits of information in a standard
insilmaril@264
  1385
presentation, for example each list item is contained in its own list.
insilmaril@264
  1386
In the end I came up with the default presentation style, which still
insilmaril@264
  1387
could be simplified, just in case you have free time\ldots
insilmaril@252
  1388
insilmaril@486
  1389
The existing templates are still work in progress, before you spend too
insilmaril@264
  1390
much time developing your own style, please contact me.  Basically the
insilmaril@264
  1391
following steps are needed to build your own style:
insilmaril@264
  1392
\begin{enumerate}
insilmaril@264
  1393
	\item Create an example in Open Office. Use a title, authors name,
insilmaril@264
  1394
	page heading etc.\ which you can easily grep for in the output file.
insilmaril@264
  1395
	
insilmaril@264
  1396
	\item Unzip  the Open Office document into a directory.
insilmaril@264
  1397
insilmaril@264
  1398
	\item The main file is called {\tt content.xml}. All data is in one
insilmaril@264
  1399
	single line. You can split the XML tags using the script {\tt
insilmaril@264
  1400
	scripts/niceXML}, which is part of the \vym distribution.
insilmaril@264
  1401
insilmaril@264
  1402
	\item Copy the output of {\tt niceXML} to {\tt
insilmaril@264
  1403
	content-template.xml}.
insilmaril@264
  1404
insilmaril@264
  1405
	\item Looking closer you will find lots of unused definitions, for
insilmaril@264
  1406
	example of styles. You can delete or simply ignore them.
insilmaril@264
  1407
insilmaril@264
  1408
	\item Try to find your title, authors name. \vym will replace the
insilmaril@264
  1409
	following strings while exporting:
insilmaril@264
  1410
	\begin{center}
insilmaril@264
  1411
	\begin{tabular}{lp{4cm}}
insilmaril@264
  1412
		{\tt <!-- INSERT TITLE -->}		& title of map \\
insilmaril@264
  1413
		{\tt <!-- INSERT AUTHOR-->	}	& author \\
insilmaril@264
  1414
		{\tt <!-- INSERT COMMENT -->}	& comment \\
insilmaril@264
  1415
		{\tt <!-- INSERT PAGES-->}		& content of map \\
insilmaril@264
  1416
	\end{tabular}
insilmaril@264
  1417
	\end{center}
insilmaril@264
  1418
	The content itself is generated in a similar way by inserting lists
insilmaril@264
  1419
	into {\tt page-template}. Here the following substitutions are made:
insilmaril@264
  1420
	\begin{center}
insilmaril@264
  1421
	\begin{tabular}{lp{7cm}}
insilmaril@264
  1422
		{\tt <!-- INSERT PAGE HEADING-->}		& heading of a page
insilmaril@264
  1423
		(mainbranch or child of mainbranch, depending on the use of
insilmaril@264
  1424
		sections) \\
insilmaril@264
  1425
		{\tt <!-- INSERT LIST -->	}	& all childs of the branch above \\
insilmaril@264
  1426
	\end{tabular}
insilmaril@264
  1427
	\end{center}
insilmaril@264
  1428
\end{enumerate}
insilmaril@264
  1429
Currently images are exported and notes just will appear as text
insilmaril@486
  1430
without formatting and colours.
insilmaril@264
  1431
insilmaril@264
  1432
insilmaril@264
  1433
insilmaril@264
  1434
insilmaril@264
  1435
\subsubsection*{XSL Transformation}
insilmaril@264
  1436
\vym uses XSL transformations while exporting (e.g. XHTML) and importing
insilmaril@264
  1437
data (e.g. KDE bookmarks). There is a little code needed to provide the
insilmaril@264
  1438
GUI, the rest is done using the {\tt .xsl} stylesheet and calling the
insilmaril@264
  1439
{\tt xsltproc} processor, which is part of libxslt, the XSLT
insilmaril@264
  1440
C  library  for  GNOME. 
insilmaril@233
  1441
insilmaril@233
  1442
\end{appendix}
insilmaril@233
  1443
\end{document}
insilmaril@28
  1444
insilmaril@125
  1445
%TODO
insilmaril@125
  1446
%\subsubsection{Menus}
insilmaril@125
  1447
%\subsubsection{Keyboard shortcuts}
insilmaril@125
  1448
%Where does vym save its settings? -> ~/.qt/vymrc
insilmaril@125
  1449
insilmaril@28
  1450
insilmaril@28
  1451
% INDEX
insilmaril@28
  1452
% mapeditor
insilmaril@28
  1453
% noteditor
insilmaril@28
  1454
% branch
insilmaril@28
  1455
% mapcenter
insilmaril@28
  1456
% heading
insilmaril@28
  1457
% flag
insilmaril@28
  1458
% orientation 
insilmaril@28
  1459
% zoom
insilmaril@28
  1460
% orientation
insilmaril@28
  1461
% Toolbar
insilmaril@28
  1462
% Zoom
insilmaril@28
  1463
% Find
insilmaril@28
  1464
% statusbar
insilmaril@28
  1465
% link
insilmaril@28
  1466
% mainbranch
insilmaril@28
  1467
% subtree
insilmaril@28
  1468
% reorder
insilmaril@28
  1469
% scroll
insilmaril@28
  1470
% fold
insilmaril@104
  1471
% vymlink
insilmaril@104
  1472
% xlink
insilmaril@125
  1473
% modMode
insilmaril@104
  1474
% context menu
insilmaril@104
  1475
% Mac OS X
insilmaril@28
  1476
insilmaril@28
  1477
insilmaril@28
  1478
insilmaril@125
  1479
\end{document}