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