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