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