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