tex/vym.tex
author insilmaril
Tue, 01 Dec 2009 11:06:41 +0000
branchrelease-1-12-maintained
changeset 78 1a72c8f24c6e
parent 76 a36a289372a6
permissions -rw-r--r--
Fixed selection which didn't show sometimes
insilmaril@76
     1
\documentclass[12pt,a4paper]{article}
insilmaril@76
     2
\usepackage[utf8]{inputenc}
insilmaril@28
     3
\usepackage{verbatim}
insilmaril@28
     4
\usepackage{hyperref}
insilmaril@28
     5
\usepackage{graphicx}
insilmaril@76
     6
%\usepackage{longtable}
insilmaril@28
     7
insilmaril@76
     8
\setlength{\headheight}{0cm}
insilmaril@76
     9
\setlength{\headsep}{0cm}
insilmaril@76
    10
\setlength{\topskip}{0cm}
insilmaril@76
    11
\setlength{\topmargin}{-0.5cm}
insilmaril@28
    12
insilmaril@76
    13
\setlength{\parskip}{1.5ex}
insilmaril@76
    14
\setlength{\parindent}{0cm}
insilmaril@76
    15
\setlength{\oddsidemargin}{0cm}
insilmaril@76
    16
\setlength{\textwidth}{16cm}
insilmaril@76
    17
\setlength{\textheight}{27cm}
insilmaril@28
    18
insilmaril@76
    19
\newlength{\maximgwidth}
insilmaril@76
    20
\setlength{\maximgwidth}{14cm}
insilmaril@76
    21
\newcommand{\maximage}[1]{	
insilmaril@76
    22
	\begin{center}
insilmaril@76
    23
		\includegraphics[width=\maximgwidth]{#1} 
insilmaril@76
    24
	\end{center}
insilmaril@76
    25
}
insilmaril@76
    26
\newcommand{\hint}[1]{
insilmaril@76
    27
	\begin{center} 
insilmaril@76
    28
		\begin{tabular}{|rp{12cm}|} \hline
insilmaril@76
    29
			{\bf Hint}:& #1\\	\hline
insilmaril@76
    30
		\end{tabular}
insilmaril@76
    31
			\marginpar{\Huge !} 
insilmaril@76
    32
	\end{center} 
insilmaril@76
    33
}
insilmaril@76
    34
insilmaril@76
    35
\newcommand{\vym}{{\sc vym }}
insilmaril@76
    36
\newcommand{\ra}{$\longrightarrow$}
insilmaril@76
    37
\newcommand{\la}{$\longleftarrow$}
insilmaril@76
    38
\newcommand{\ua}{$\uparrow$}
insilmaril@76
    39
\newcommand{\da}{$\downarrow$}
insilmaril@76
    40
\newcommand{\key}[1]{[#1]}
insilmaril@76
    41
insilmaril@76
    42
\newenvironment{code}[1] { \verbatim #1}{\endverbatim  }
insilmaril@28
    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@76
    57
\begin{document}
insilmaril@76
    58
\title{
insilmaril@76
    59
	\includegraphics[width=8cm]{images/vym-logo-new.png}
insilmaril@76
    60
	\\
insilmaril@76
    61
VYM \\ -- \\View Your Mind\\ {\small Version 1.12.0}}
insilmaril@76
    62
\author{\textcopyright Uwe Drechsel  }
insilmaril@28
    63
insilmaril@28
    64
insilmaril@28
    65
\maketitle
insilmaril@28
    66
insilmaril@76
    67
\newpage
insilmaril@76
    68
insilmaril@28
    69
\tableofcontents
insilmaril@28
    70
insilmaril@28
    71
\newpage
insilmaril@28
    72
insilmaril@76
    73
\section*{Credits}
insilmaril@76
    74
Many people have sent me their feedback and ideas, and all of that has
insilmaril@76
    75
helped a lot to make \vym better. Thanks to all of you!
insilmaril@76
    76
insilmaril@76
    77
For this manual I would like to send some special thanks to
insilmaril@76
    78
insilmaril@76
    79
\begin{itemize}
insilmaril@76
    80
	\item {\em Peter Adamson} for lots of feedback and proofreading of my
insilmaril@76
    81
	      far from perfect english
insilmaril@76
    82
	\item The team of {\em AClibre (Academia y Conocimiento Libre)}
insilmaril@76
    83
          in Colombia for their translation of
insilmaril@76
    84
          the manual to spanish:
insilmaril@76
    85
		  \begin{center}
insilmaril@76
    86
			\begin{tabular}{|p{7cm}|p{5.5cm}|} \hline
insilmaril@76
    87
				Encargado & Actividad \\ \hline
insilmaril@76
    88
				\begin{itemize}
insilmaril@76
    89
				   \item Vanessa Carolina Guti\'errez Sanchez
insilmaril@76
    90
				   \item Erika Tatiana Luque Melo
insilmaril@76
    91
				   \item Jeffrey Steve Borb\'on Sanabria
insilmaril@76
    92
				   \item John Edisson Ortiz Rom\'an
insilmaril@76
    93
				\end{itemize} &
insilmaril@76
    94
				\begin{itemize}
insilmaril@76
    95
					\item Traducci\'onl
insilmaril@76
    96
					\item Revisi\'on y correcciones varias
insilmaril@76
    97
					\item Estructuraci\'on y exporte
insilmaril@76
    98
					\item Revisi\'on y correcciones varias
insilmaril@76
    99
				\end{itemize}     \\ \hline
insilmaril@76
   100
			\end{tabular}	
insilmaril@76
   101
		\end{center}
insilmaril@76
   102
\end{itemize}
insilmaril@76
   103
\newpage
insilmaril@76
   104
insilmaril@76
   105
insilmaril@28
   106
\section{Introduction}
insilmaril@28
   107
\subsection{What is a \vym map?}
insilmaril@76
   108
A \vym map (abbreviated below as {\em map}) is a tree-like structure:
insilmaril@76
   109
\maximage{images/example1.png}
insilmaril@76
   110
Such maps can be drawn by hand on a sheet of paper or flip chart and help to
insilmaril@76
   111
structure your thoughts. While a tree like structure like the illustration above can be
insilmaril@76
   112
drawn manually \vym offers much more features to work with such maps.
insilmaril@76
   113
\vym is not just another drawing software application, but a tool to store and modify
insilmaril@76
   114
information in an intuitive way. For example you can reorder parts of
insilmaril@76
   115
the map by pressing a key or add various pieces of information like a complete
insilmaril@76
   116
email by a simple mouse click.
insilmaril@28
   117
insilmaril@76
   118
Once you have finished collecting and organising your ideas, you can
insilmaril@76
   119
easily generate a variety of outputs including for example a
insilmaril@76
   120
presentation in Open~Office based on a {\em map}.
insilmaril@76
   121
insilmaril@76
   122
\hint{You find the map shown above and others by clicking \begin{center}Help \ra Open vym
insilmaril@76
   123
examples\end{center} in the menu bar.}
insilmaril@76
   124
insilmaril@76
   125
\subsection{Why should I use {\em maps}? Time, Space and your Brain.}
insilmaril@28
   126
\subsubsection*{Space}
insilmaril@76
   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@76
   129
side and also your creative side (e.g. by using pictures, colours and
insilmaril@76
   130
keywords in a map, often called {\em anchors}).  It is a technique to help
insilmaril@76
   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@76
   135
old fashioned 'notes'. Your brain memorizes things by associating them with
insilmaril@76
   136
other things -- a {\em map} makes use of those connections and stimulates
insilmaril@28
   137
new asccociations. 
insilmaril@28
   138
insilmaril@76
   139
insilmaril@28
   140
\subsubsection*{Your Brain}
insilmaril@76
   141
In 1960 Prof. {\sc Roger Sperry} discovered that both hemispheres
insilmaril@76
   142
of the human brain undertake different tasks (of course both of them
insilmaril@76
   143
basically {\em can} do the same): 
insilmaril@76
   144
\begin{center}
insilmaril@76
   145
\begin{tabular}{|p{5.5cm}|p{5.5cm}|} \hline
insilmaril@76
   146
	Left side & Right side \\ \hline
insilmaril@76
   147
	\begin{itemize}
insilmaril@76
   148
	   \item verbal speech and writing 
insilmaril@76
   149
	   \item numbers
insilmaril@76
   150
	   \item logical thinking
insilmaril@76
   151
	   \item analysing and details
insilmaril@76
   152
	   \item science
insilmaril@76
   153
	   \item linear thinking
insilmaril@76
   154
	   \item concept of time
insilmaril@76
   155
	\end{itemize} &
insilmaril@76
   156
	\begin{itemize}
insilmaril@76
   157
		\item body language
insilmaril@76
   158
		\item visual thinking, day dreams
insilmaril@76
   159
		\item intuition and emotion
insilmaril@76
   160
		\item overview of things
insilmaril@76
   161
		\item creativity
insilmaril@76
   162
		\item art, music, dancing
insilmaril@76
   163
		\item non-linear thinking, connecting things
insilmaril@76
   164
		\item spatial awareness
insilmaril@76
   165
	\end{itemize}     \\ \hline
insilmaril@76
   166
\end{tabular}	
insilmaril@76
   167
\end{center}
insilmaril@76
   168
In our science oriented western society we have learned to mainly rely on our
insilmaril@76
   169
left side of the brain, the "rational" one. In other cultures, such as the native americans and other "old" cultures, the right
insilmaril@76
   170
side is much more important. {\em Map} are just one way to stimulate the
insilmaril@76
   171
other side and make use of additional resources we all have.
insilmaril@28
   172
insilmaril@28
   173
insilmaril@76
   174
\subsection{Where could I use a {\em map}?}
insilmaril@76
   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@76
   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@76
   182
    \item to brainstorm solutions to problems
insilmaril@76
   183
    \item to record the tasks when planning a project
insilmaril@28
   184
\end{itemize}
insilmaril@28
   185
insilmaril@76
   186
\subsection{What you shouldn't do with a {\em map}...}
insilmaril@76
   187
A {\em map} drawn by somebody shows the way that the author thinks. There is
insilmaril@76
   188
no question of right or wrong in the way it is drawn, so there is no way to criticise
insilmaril@76
   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@76
   190
insilmaril@76
   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@76
   196
\subsection{Internet Ressources} 
insilmaril@76
   197
A good starting point to learn more about Mindmaps in general is Wikipedia:
insilmaril@76
   198
\begin{itemize}
insilmaril@76
   199
	\item English: 
insilmaril@76
   200
		\href{http://en.wikipedia.org/wiki/Mind_map}{http://en.wikipedia.org/wiki/Mind\_map}
insilmaril@76
   201
	\item German: 
insilmaril@76
   202
		\href{http://de.wikipedia.org/wiki/Mindmap}{http://de.wikipedia.org/wiki/Mindmap}
insilmaril@76
   203
\end{itemize}
insilmaril@28
   204
insilmaril@76
   205
insilmaril@76
   206
insilmaril@76
   207
insilmaril@76
   208
\section{The Concept of the \vym application}
insilmaril@28
   209
%TODO may add a general introduction here...
insilmaril@76
   210
\subsection{The Mainwindow and its satellites} \label{satellite}
insilmaril@76
   211
\vym comes with several windows, the central one being the {\em
insilmaril@76
   212
mapeditor}.
insilmaril@76
   213
More windows, each having a special purpose, can be opened and arranged
insilmaril@76
   214
around the mainwindow\footnote{
insilmaril@76
   215
	The advantage of having separate window instead of integrating them
insilmaril@76
   216
	in a combined workspace is flexibility in arranging the windows. For
insilmaril@76
   217
	example I usually have the {\em noteeditor} "behind" the {\em
insilmaril@76
   218
	mapeditor}. On Linux my windowmanager (KDE) allows me to enter text
insilmaril@76
   219
	into a small visible corner of the {\em noteeditor} withour clicking
insilmaril@76
   220
	the mouse button in it. I just push the mouse around to set the
insilmaril@76
   221
	window focus, a concept which is useful also working with 
insilmaril@76
   222
	\href{http://www.gimp.org}{http://www.gimp.org}.
insilmaril@76
   223
}. 
insilmaril@76
   224
The image below shows the {\em mapeditor}
insilmaril@76
   225
together with the often used {\em noteeditor}: 
insilmaril@76
   226
\maximage{images/windows.png}
insilmaril@76
   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@76
   233
 
insilmaril@76
   234
Here is a list of the available satellite windows:
insilmaril@76
   235
\begin{itemize}
insilmaril@76
   236
	\item Noteeditor (see \ref {noteeditor})
insilmaril@76
   237
	\item Historywindow (see \ref{historywindow})
insilmaril@76
   238
	\item Branch Property Window (see \ref{propwindow})
insilmaril@76
   239
\end{itemize}
insilmaril@28
   240
insilmaril@76
   241
insilmaril@76
   242
\subsection{Menus and Context menus}
insilmaril@76
   243
At the top of each window you will find the menubar. The options provided there
insilmaril@76
   244
are similar to those you are probably used to from other applications. Note that
insilmaril@76
   245
many (and even more) options are available via {\em context menus}. Those
insilmaril@76
   246
are available if you right-click onto an object in a map (on Mac~OS~X
insilmaril@76
   247
Command-Click).
insilmaril@76
   248
insilmaril@76
   249
\subsection{Toolbars}
insilmaril@76
   250
The toolbars in the mainwindows give quick access to many functions and
insilmaril@76
   251
also display the state of selected objects in the map. For example a
insilmaril@76
   252
branch may show certain {\em flags}, the corresponding flags are also
insilmaril@76
   253
set in the toolbar. 
insilmaril@76
   254
insilmaril@76
   255
\hint {You can reposition all toolbars by simply grabbing and
insilmaril@76
   256
dragging them with the toolbar handle to a new position. For example you
insilmaril@76
   257
can move the flags-toolbar from its original horizontal position on top
insilmaril@76
   258
of the mapeditor to a vertical position on the right side.  Or just
insilmaril@76
   259
insert it again at its original position. Also hiding some of the
insilmaril@76
   260
toolbars is possible by right-clicking on the toolbar handle.}
insilmaril@76
   261
insilmaril@76
   262
\subsection{Maps}
insilmaril@76
   263
The  {\em map} itself has always a {\em mapcenter}.  The
insilmaril@76
   264
mapcenter has {\em branches} radiating out from the centre just like the trunk 
insilmaril@76
   265
of a tree. Each branch in turn may have branches again.
insilmaril@76
   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@76
   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@76
   277
	\maximage{images/default-flags.png}
insilmaril@28
   278
These are called {\em flags} and can be used to mark branches in the
insilmaril@76
   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@76
   281
information, e.g. when a note is attached to a  particular branch.
insilmaril@76
   282
insilmaril@76
   283
By default some of these flags are set exclusively e.g. when the 
insilmaril@76
   284
"thumb-up" flag is set, then the "thumb down" is reset and vice
insilmaril@76
   285
versa. You can change this default behaviour in the settings menu (see
insilmaril@76
   286
\ref{settings}).
insilmaril@28
   287
insilmaril@28
   288
\section{Mapeditor} \label {mapeditor}
insilmaril@28
   289
\subsection{Start a new map}
insilmaril@76
   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@76
   294
left-clicking with the mouse. It will be highlighted yellow to show that is
insilmaril@76
   295
selected. There are several ways to add a new branch to the center:
insilmaril@28
   296
\begin{itemize}
insilmaril@76
   297
	\item Using the mouse: Open the context menu by clicking with the
insilmaril@76
   298
	right mouse button (CTRL-Click on Mac) onto the
insilmaril@76
   299
	mapcenter and choose Add \ra Add branch as child
insilmaril@76
   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@76
   305
Sometimes it comes in handy to be able to add a new branch above or below the current
insilmaril@76
   306
one. 
insilmaril@76
   307
\begin{itemize}
insilmaril@76
   308
	\item Use \key{Shift-A} to add a branch above the selected one or... 
insilmaril@76
   309
	\item \key{Ctrl-A} to add one below. 
insilmaril@76
   310
\end{itemize}
insilmaril@76
   311
It is also
insilmaril@76
   312
possible to add a branch in such a way, that the current selection
insilmaril@76
   313
becomes the child of the new branch, which is like inserting it {\em
insilmaril@76
   314
before} the selection. This can be done using the context menu.
insilmaril@76
   315
insilmaril@76
   316
\hint{To delete a branch press \key{CTRL-X}. If enabled in the Settings
insilmaril@76
   317
menu (see \ref{settings}), you can also use the \key{Del} key.}
insilmaril@28
   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@76
   322
arrow keys. Depending on the {\em orientation} of a branch tap
insilmaril@76
   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@76
   325
{\em subtree}, you can use \key{PgUp} and \key{PgDn} to go up and down. You can
insilmaril@76
   326
also use \key{Home} and \key{End} to select the first and last branch.
insilmaril@28
   327
insilmaril@28
   328
insilmaril@76
   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@76
   331
larger than the mapeditor window. You can use the scrollbars on the
insilmaril@76
   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@76
   333
mouse pointer will change from an arrow to a hand, now move or drag the visible
insilmaril@76
   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@76
   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@76
   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@76
   346
			\includegraphics[width=3cm]{images/zoom-buttons.png}
insilmaril@28
   347
		\end{center}	
insilmaril@28
   348
\end{itemize}	
insilmaril@76
   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@76
   356
	\includegraphics[width=6cm]{images/find-window.png}
insilmaril@28
   357
\end{center}	
insilmaril@76
   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@76
   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@76
   362
\subsubsection*{Keep the overview -- scroll a part of the map}
insilmaril@76
   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@76
   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@76
   366
broadsheet newspaper. You can scroll or fold the paper to a small roll, leaving just
insilmaril@76
   367
the headline visible.
insilmaril@28
   368
insilmaril@76
   369
To scroll or unscroll a branch and its children,
insilmaril@28
   370
\begin{itemize}
insilmaril@76
   371
	\item press the \key{S}
insilmaril@28
   372
	\item press the middle-mouse button or
insilmaril@76
   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@76
   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@28
   379
possible to unscroll all branches using "Edit\ra Unscroll all scrolled
insilmaril@28
   380
branches".
insilmaril@28
   381
insilmaril@76
   382
You can also hide parts of the map while exporting it e.g. to a webpage
insilmaril@76
   383
or a presentation, see \ref{hideexport} for details.
insilmaril@28
   384
insilmaril@28
   385
\subsection{Modify and move branches}
insilmaril@76
   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@76
   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@76
   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@76
   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@76
   433
\subsection{Colours and Images - Using the right side of your brain}
insilmaril@76
   434
\subsubsection*{Change colour of a heading}
insilmaril@76
   435
You can also use colours to add more information to a map, e.g. use
insilmaril@76
   436
red, green and more colours to prioritize tasks. Again you can
insilmaril@28
   437
\begin{itemize}
insilmaril@76
   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@76
   441
			\includegraphics[width=3cm]{images/color-buttons.png}
insilmaril@28
   442
		\end{center}	
insilmaril@28
   443
\end{itemize}
insilmaril@76
   444
The first button (black in the graphic above) shows the current colour.
insilmaril@76
   445
Clicking on it let's you choose another colour. You can also "pick"
insilmaril@76
   446
another colour by selecting a branch with the desired colour and using the
insilmaril@76
   447
"pick colour" button. Both of the icons showing a palette actually apply
insilmaril@76
   448
the current colour to the selected branch. While the first one just
insilmaril@76
   449
colours the heading of the selection, the last one also colours all the
insilmaril@76
   450
children of the selected branch.
insilmaril@28
   451
insilmaril@28
   452
%tipp
insilmaril@76
   453
A very useful function is the "copy colour" using the mouse: Select the
insilmaril@76
   454
branch which should get the new colour, then press \key{Ctrl} and
insilmaril@76
   455
simultanously click with left-mouse on another branch to copy its colour
insilmaril@76
   456
to the first one. Here the children of the selection also will get the new
insilmaril@76
   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@76
   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@76
   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@76
   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@76
   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@76
   477
The easiest way to add an image to a branch is by dragging it e.g. from a
insilmaril@76
   478
webbrowser to the mapeditor while a branch is selected there.
insilmaril@76
   479
insilmaril@76
   480
You can also add an image to a branch by opening the context menu of the
insilmaril@76
   481
branch. Right click the selected branch, choose "Add Image". A
insilmaril@76
   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@76
   486
While an image is selected in the dialog, a preview of the
insilmaril@76
   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@76
   495
to save the image. 
insilmaril@76
   496
insilmaril@76
   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@76
   515
A frame can be added to a branch in the {\em property window} (see
insilmaril@76
   516
\ref{propwindow}). 
insilmaril@76
   517
Alternatively, you can use use images as frames. Have a look at the demo
insilmaril@76
   518
map {\tt todo.vym} as an example, where the mapcenter is a cloud. You
insilmaril@76
   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@76
   521
which don't use a rectangular borderline, just like that cloud.
insilmaril@28
   522
insilmaril@28
   523
insilmaril@76
   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@76
   529
	\item Right clicking on the canvas, which will open a context menu
insilmaril@28
   530
\end{itemize}
insilmaril@28
   531
insilmaril@76
   532
\subsubsection*{Background }
insilmaril@76
   533
The colour is set (and also displayed) as "Set background colour".
insilmaril@76
   534
Alternatevily you can set an background image, though this is not
insilmaril@76
   535
recommended in general. Working on the map becomes slow and the image
insilmaril@76
   536
currently cannot be positioned freely.
insilmaril@28
   537
insilmaril@76
   538
\subsubsection*{Link colour}
insilmaril@76
   539
Links connecting branches can be coloured in one of two ways:
insilmaril@28
   540
\begin{itemize}
insilmaril@76
   541
	\item use the same colour for the heading and for the branch link line.
insilmaril@76
   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@76
   544
The latter can be set with "Set link colour". Check or uncheck the "Use
insilmaril@76
   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@76
   556
The "thick" styles only apply to links starting at the mapcenter, link lines for the rest
insilmaril@76
   557
of the map are always painted "thin".
insilmaril@28
   558
insilmaril@28
   559
insilmaril@76
   560
\subsection{Links to other documents and webpages}
insilmaril@76
   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@76
   566
In addition to the external links there also internal ones, leading from one
insilmaril@76
   567
branch in a map to another one. Those are called {\em XLinks} and are explained
insilmaril@76
   568
in section~\ref{xlinks}.
insilmaril@28
   569
insilmaril@28
   570
\subsubsection*{Webbrowser}
insilmaril@76
   571
Modern Webbrowsers like {\tt konqueror and Firefox} are able to display various
insilmaril@76
   572
types of files, both local or on the internet. To enter the URL of
insilmaril@76
   573
any document, press \key{U} or right-click  onto a branch to open the contextmenu then choose
insilmaril@76
   574
"References\ra Edit URL". If you want to use a file dialog to
insilmaril@76
   575
conveniently choose a local file you can use~\key{U}.
insilmaril@76
   576
insilmaril@76
   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@76
   580
	The browser can be changed in the Settings Menu (see \ref{settings}).}
insilmaril@76
   581
will be launched.
insilmaril@28
   582
\begin{center}
insilmaril@76
   583
	\includegraphics[width=0.5cm]{images/flag-url.png}
insilmaril@28
   584
\end{center}
insilmaril@76
   585
For more information on working with bookmarks and webbrowsers see
insilmaril@76
   586
section \ref{bookmarks}.
insilmaril@76
   587
insilmaril@76
   588
In the context menu there is also an option to open all URLs found
insilmaril@76
   589
in the selected subtree of the map. That's useful to simultanously open
insilmaril@76
   590
a collection of URLs in the webbrowser, especially if the browser can
insilmaril@76
   591
open them in tabs (like Konqueror).
insilmaril@76
   592
insilmaril@28
   593
insilmaril@28
   594
\subsubsection*{\vym map}
insilmaril@76
   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@76
   598
	\includegraphics[width=0.5cm]{images/flag-vymlink.png}
insilmaril@28
   599
\end{center}
insilmaril@76
   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@76
   601
multiple maps). To delete an existing link, just right click the branch and select "Delete \vym link".
insilmaril@76
   602
insilmaril@76
   603
In the context menu there is also an option to open all vymlinks found
insilmaril@76
   604
in the selected subtree of the map. That's useful to simultanously open
insilmaril@76
   605
a collection of related maps.
insilmaril@28
   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@76
   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@76
   635
use the noteeditor. 
insilmaril@76
   636
	\maximage{images/noteeditor.png}
insilmaril@76
   637
This editor displays text associated with a branch selected in the mapeditor. The noteeditor
insilmaril@76
   638
shows different background colours depending on whether text is associated with a selected branch.
insilmaril@28
   639
insilmaril@76
   640
\subsection{States}
insilmaril@28
   641
Before you can type or paste text into it, you have
insilmaril@76
   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@76
   646
	\item white: some text has been entered
insilmaril@28
   647
\end{itemize}	
insilmaril@76
   648
In the mapeditor itself, to signal that there is a note with more
insilmaril@76
   649
information for a particular branch, a little "note" flag will appear next
insilmaril@76
   650
to the heading of the branch. This is illustrated in the lower branch on the right hand side:
insilmaril@76
   651
	\maximage{images/branches-flags.png}
insilmaril@28
   652
insilmaril@76
   653
\subsection{Import and export notes}
insilmaril@76
   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@76
   656
or write it. In the Note Editor use "File\ra~Import" and "File\ra~Export" to do so. 
insilmaril@28
   657
insilmaril@76
   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@76
   663
\subsection{RichText: Colours, paragraphs and formatted text}
insilmaril@76
   664
\vym supports formatted text (QT Rich Text) in the noteeditor since
insilmaril@76
   665
version 1.4.7.  Colours and text attributes (e.g. italic, bold) can be
insilmaril@76
   666
set with the buttons above the text.  
insilmaril@76
   667
%The text itself is divided into
insilmaril@76
   668
%paragraphs. For each paragraph the format can be set (e.g. centered,
insilmaril@76
   669
%right). A paragraph is ended when a \key{Return} is entered. If you just
insilmaril@76
   670
%want to begin a new line, press \key{CTRL-Return}.
insilmaril@28
   671
insilmaril@76
   672
\subsection{Fonts and how to switch them quickly}
insilmaril@76
   673
The noteeditor is designed to be used for simple notes, not really as a full
insilmaril@76
   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@76
   678
Two default fonts are supported which can be set in the Settings menu
insilmaril@76
   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@76
   686
	\includegraphics[width=0.5cm]{images/formatfixedfont.png}
insilmaril@28
   687
\end{center}
insilmaril@76
   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@76
   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@76
   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@76
   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@28
   703
insilmaril@28
   704
\section{Hello world}
insilmaril@76
   705
This section is about how \vym can interact with other applications.
insilmaril@76
   706
Many applications can now read and write their data using XML, the
insilmaril@76
   707
eXtensible Markup Language. \vym also uses XML to save its maps, see
insilmaril@76
   708
\ref{fileformat} for a more detailed description. 
insilmaril@28
   709
insilmaril@76
   710
So if you make use of another application that understands XML, chances are good that someone
insilmaril@76
   711
could write import/export filters for \vym. Volunteers are always
insilmaril@76
   712
welcome ;-)
insilmaril@76
   713
insilmaril@76
   714
\subsection{Import} \label{import}
insilmaril@76
   715
insilmaril@76
   716
\subsubsection*{KDE Bookmarks}
insilmaril@76
   717
The integrated bookmark editor in KDE (Konqueror etc.) is somewhat limited, so why not
insilmaril@76
   718
use \vym to maintain the bookmark mess? To create a new map containing
insilmaril@76
   719
your current KDE bookmarks just choose
insilmaril@28
   720
\begin{itemize}
insilmaril@76
   721
	\item File \ra Import\ra KDE Bookmarks
insilmaril@28
   722
\end{itemize}
insilmaril@76
   723
insilmaril@76
   724
\subsubsection*{Mind Manager}
insilmaril@76
   725
\vym has currently a very basic import filter to convert maps created by
insilmaril@76
   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@76
   727
\href{http://mindjet.com}{http://mindjet.com}} into \vym maps. Notes and
insilmaril@76
   728
pictures are not converted at the moment. You can import files with
insilmaril@76
   729
\begin{itemize}
insilmaril@76
   730
	\item File \ra Import\ra Mind Manager
insilmaril@76
   731
\end{itemize}
insilmaril@76
   732
insilmaril@76
   733
insilmaril@76
   734
\subsubsection*{Directory structure}
insilmaril@76
   735
\vym can read a directory structure. This is mainly for
insilmaril@76
   736
testing \vym e.g. to easily create huge maps used for benchmarks (yes,
insilmaril@76
   737
there is still room to optimize \vym ;-)
insilmaril@76
   738
insilmaril@76
   739
insilmaril@76
   740
insilmaril@76
   741
insilmaril@76
   742
\subsection{Export}  \label{export}
insilmaril@76
   743
\label{hideexport}
insilmaril@76
   744
Often you may not want to export the whole map, but just parts of it. For
insilmaril@76
   745
example you may have additional info you want to talk about in a
insilmaril@76
   746
presentation, while those parts should not be visible to the audience.
insilmaril@76
   747
To achieve this you can "hide" parts of the map during exports by
insilmaril@76
   748
setting the "hide in export" flag.
insilmaril@76
   749
\begin{center}
insilmaril@76
   750
	\includegraphics[width=0.5cm]{images/flag-hideexport.png}
insilmaril@76
   751
\end{center}
insilmaril@76
   752
You can toggle this flag in the toolbar or by pressing \key{H}.
insilmaril@76
   753
Note that there is a global option in the settings menu (
insilmaril@76
   754
\ref{settings}) to toggle the use of this flag. By default the flag is
insilmaril@76
   755
enabled.
insilmaril@76
   756
insilmaril@76
   757
\subsubsection*{Open Office}
insilmaril@76
   758
Open Office beginning with version~2 uses the so called "Open Document Format", which can be written by \vym. The options are
insilmaril@76
   759
currently limited, but it possible to export presentations which can be
insilmaril@76
   760
opened in Open Office Impress. By selecting
insilmaril@76
   761
\begin{itemize}
insilmaril@76
   762
	\item File  \ra Export\ra Open Office
insilmaril@76
   763
\end{itemize}
insilmaril@76
   764
you get a file dialogue where you can choose the output file and the
insilmaril@76
   765
file type:
insilmaril@76
   766
	\maximage{images/export-oo.png}
insilmaril@76
   767
The file types represent various templates, which can be created with
insilmaril@76
   768
some manual work from an existing Open Office document. The structure of
insilmaril@76
   769
\vym map is then inserted into a template. 
insilmaril@76
   770
There are some limitations at the moment:
insilmaril@76
   771
\begin{itemize}
insilmaril@76
   772
	\item \vym can't take care of page lengths, so you have to check and
insilmaril@76
   773
	probably reedit in Open Office to avoid text running over the end of
insilmaril@76
   774
	a page
insilmaril@76
   775
	\item Images and flags are not used at the moment
insilmaril@76
   776
	\item Notes are just written as plain text, without RichText 
insilmaril@76
   777
	\item The full range of templates are not available in all distributions.	
insilmaril@76
   778
\end{itemize}
insilmaril@76
   779
Some of the templates make use of {\em sections} i.e sections insert the
insilmaril@76
   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@76
   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@76
   795
\subsubsection*{\LaTeX}
insilmaril@76
   796
\vym can generate an input file for \LaTeX. Currently this is considered
insilmaril@76
   797
as experimental, there are no options (yet). 
insilmaril@76
   798
By selecting
insilmaril@76
   799
\begin{itemize}
insilmaril@76
   800
	\item File  \ra Export\ra \LaTeX 
insilmaril@76
   801
\end{itemize}
insilmaril@76
   802
you will be asked in a file dialog for the name of the output file. This
insilmaril@76
   803
file may then be included in a \LaTeX document using command: 
insilmaril@76
   804
\begin{verbatim}
insilmaril@76
   805
	\include{inputfile.tex}
insilmaril@76
   806
\end{verbatim}
insilmaril@76
   807
insilmaril@76
   808
\subsubsection*{KDE Bookmarks}
insilmaril@76
   809
\vym will overwrite the KDE bookmarks file and then try to notify
insilmaril@76
   810
running Konquerors via DCOP of the changed file. \vym does not create a
insilmaril@76
   811
backup!
insilmaril@76
   812
\begin{itemize}
insilmaril@76
   813
	\item File \ra Export \ra KDE Bookmarks
insilmaril@76
   814
\end{itemize}
insilmaril@76
   815
insilmaril@76
   816
insilmaril@76
   817
\subsubsection*{XHTML (Webpages)}
insilmaril@76
   818
insilmaril@76
   819
This is the format to use if you wish to create a webpage. To see an example
insilmaril@76
   820
visit the \vym homepage: 
insilmaril@76
   821
\href{http://www.InSilmaril.de/vym}{www.InSilmaril.de/vym}
insilmaril@76
   822
insilmaril@76
   823
Some explanation on how this works: 
insilmaril@76
   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@76
   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@76
   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@76
   836
	If set to yes, \vym will colour the headings in the text part  with the
insilmaril@76
   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@76
   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@76
   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@76
   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@76
   858
\subsubsection*{Export a part of a map}
insilmaril@76
   859
Select a branch you want to export together with its children, then open
insilmaril@76
   860
the context menu and choose {\em Save Selection}. This will create a
insilmaril@76
   861
file with the suffix {\tt .vyp}, which is an abbreviation for \lq vym
insilmaril@76
   862
part\rq.
insilmaril@28
   863
insilmaril@28
   864
insilmaril@76
   865
\section{Advanced Editing}
insilmaril@76
   866
insilmaril@76
   867
\subsection{Properties of an object} 
insilmaril@76
   868
For any branch you can open a satellite window (see \ref{satellite}):
insilmaril@76
   869
the {\em property window}:
insilmaril@76
   870
\begin{center}
insilmaril@76
   871
	\includegraphics[width=8cm]{images/propwindow.png}
insilmaril@76
   872
	\label{propwindow}
insilmaril@76
   873
\end{center}
insilmaril@76
   874
%FIXME create screenshot
insilmaril@76
   875
%FIXME explain the tabs
insilmaril@76
   876
insilmaril@76
   877
\begin{itemize}
insilmaril@76
   878
	\item Frame
insilmaril@76
   879
	\item Link (see \ref{hideunselected})
insilmaril@76
   880
	\item Layout (see \ref{incimg})
insilmaril@76
   881
\end{itemize}
insilmaril@76
   882
insilmaril@76
   883
\subsection{Changing the history: Undo and Redo}
insilmaril@76
   884
\vym keeps track of all changes done in a map. The default number of
insilmaril@76
   885
changes which can be undone is~75. The complete history can be seen in
insilmaril@76
   886
the {\em historywindow}:
insilmaril@76
   887
	\maximage{images/historywindow.png}
insilmaril@76
   888
	\label{historywindow}
insilmaril@76
   889
A single step back be undone or redone with \key{CTRL-Z} or \key{CTRL-Y},
insilmaril@76
   890
or by using the buttons in the toolbar or the {\em historywindow}.
insilmaril@76
   891
Inside the {\em historywindow}, you can click on a line to unwind all
insilmaril@76
   892
actions done until that point in time -- or redo all changes by clicking
insilmaril@76
   893
on the last line.
insilmaril@76
   894
insilmaril@76
   895
\hint{
insilmaril@76
   896
	You can "paste from the past": Go back in time by e.g. with
insilmaril@76
   897
	\key{CTRL-Z}, then copy to clipboard by pressing \key{CTRL-C}.
insilmaril@76
   898
insilmaril@76
   899
	Now do all actions again, e.g. by \key{CTRL-Y} or clicking on the
insilmaril@76
   900
	last action in {\em historywindow}. Now paste from the past with
insilmaril@76
   901
	\key{CTRL-V}.
insilmaril@76
   902
}
insilmaril@76
   903
insilmaril@76
   904
\subsection{Macros} \label{macros}
insilmaril@76
   905
Macros have been added to \vym in version~1.9.0. 
insilmaril@76
   906
So far they have a preliminary character, maybe they are going to be
insilmaril@76
   907
replaced by full-featured scripting functionality later (though the
insilmaril@76
   908
commands will be more or less the same).
insilmaril@76
   909
insilmaril@76
   910
Each function key
insilmaril@76
   911
\key{F1} to \key{F12} holds a macro, which is executed on the current
insilmaril@76
   912
selection if the key is pressed. The default macros change the colour of
insilmaril@76
   913
a subtree or set the frame of a branch:
insilmaril@76
   914
\begin{center}
insilmaril@76
   915
	\includegraphics[width=8cm]{images/macros.png}
insilmaril@76
   916
\end{center}
insilmaril@76
   917
Each macro is a \vym script, which is executed when the associated key
insilmaril@76
   918
is pressed. The default location of the scripts can be changed in the
insilmaril@76
   919
Settings menu. More information on using scripts in \vym is found in
insilmaril@76
   920
[\ref{settings})
insilmaril@76
   921
appendix~\ref{scripts}.
insilmaril@76
   922
insilmaril@76
   923
\subsection{Bookmarks} \label{bookmarks}
insilmaril@76
   924
\subsubsection*{Open new tabs instead of new windows}
insilmaril@76
   925
If you use konqueror as your browser, \vym will remember the konqueror session which
insilmaril@76
   926
was opened first by \vym. You can also press \key{Ctrl} and click to
insilmaril@76
   927
open the link in a new tab.
insilmaril@76
   928
insilmaril@76
   929
\vym can also open a new tab in Mozilla or Firefox using the remote
insilmaril@76
   930
command\footnote{\href{http://www.mozilla.org/unix/remote.html}{http://www.mozilla.org/unix/remote.html}}
insilmaril@76
   931
of these browsers.
insilmaril@76
   932
insilmaril@76
   933
\subsubsection*{Drag and Drop}
insilmaril@76
   934
If you want to keep bookmarks in a map, select a branch where you want
insilmaril@76
   935
to add the bookmark, then simply drag the URL from your browser to the
insilmaril@76
   936
map. Also you could use an existing heading as URL: Right click onto the
insilmaril@76
   937
branch and select "Use heading for URL".
insilmaril@76
   938
insilmaril@76
   939
insilmaril@76
   940
\subsubsection*{Directly access bookmark lists of a browser}
insilmaril@76
   941
Please see the sections \ref{import} and \ref{export} about
insilmaril@76
   942
Import and Export filters.
insilmaril@76
   943
insilmaril@76
   944
\subsubsection*{Special URLs}
insilmaril@76
   945
\vym can turn an existing heading of a branch into an URL. Currently
insilmaril@76
   946
this works for Bugentries in the Novell Bugtracking system: Open the
insilmaril@76
   947
context menu of a branch (usually by right-clicking it) and select
insilmaril@76
   948
\begin{itemize}
insilmaril@76
   949
	\item Create URL to Bugzilla
insilmaril@76
   950
\end{itemize}
insilmaril@76
   951
The URL will be build from the number in the heading.
insilmaril@76
   952
insilmaril@76
   953
\subsection{Associating images with a branch} \label{incimg}
insilmaril@76
   954
The default setting for an image is for it to float "freely". Images can be
insilmaril@76
   955
positioned anywhere on the canvas, but may end up in the same place as other
insilmaril@76
   956
parts of the map obscuring that part of the map.
insilmaril@76
   957
insilmaril@76
   958
The solution is to insert or include them "into" a branch. This can be done via
insilmaril@76
   959
the property window (see \ref{propwindow}):
insilmaril@76
   960
\begin{itemize}
insilmaril@76
   961
	\item Include images horizontally
insilmaril@76
   962
	\item Include images vertically
insilmaril@76
   963
\end{itemize}
insilmaril@76
   964
The image is still positioned relative to its parent branch, but the
insilmaril@76
   965
heading and border of the branch frame adapt to the floating image, see below: 
insilmaril@76
   966
	\maximage{images/includeImages.png}
insilmaril@76
   967
insilmaril@76
   968
\subsection{Modifier Modes} 
insilmaril@76
   969
Modifiers are for example the \key{Shift}- the \key{Ctrl}- ot the \key{Alt}-keys. When
insilmaril@76
   970
pressed while applying mouse actions, they will cause \vym to use
insilmaril@76
   971
a "modified" version of the action which usually would be done. 
insilmaril@76
   972
insilmaril@76
   973
%\key{Ctrl} or \key{Alt}is pressed while releasing the branch, it will be
insilmaril@76
   974
%added above/below the target, not as child of the target.
insilmaril@76
   975
insilmaril@76
   976
Without a modifier key pressed, the first mouse click on a branch just selects
insilmaril@76
   977
it. For the behaviour of the \key{Ctrl} modifier there are several
insilmaril@76
   978
options, which can be set from the modifier toolbar:
insilmaril@76
   979
\begin{center}
insilmaril@76
   980
	\includegraphics[width=3cm]{images/modmodes.png}
insilmaril@76
   981
\end{center}
insilmaril@76
   982
The default mode is to copy the colour from the clicked branch to the already
insilmaril@76
   983
selected branch. The figure above shows the toolbar with the default modifier 
insilmaril@76
   984
selected. The second modifier
insilmaril@76
   985
let's you easily copy a whole branch with a single click. The third
insilmaril@76
   986
modifier lets you create links between branches called {\em xLinks}.
insilmaril@76
   987
They will be explained in the next section \ref{xlinks}.
insilmaril@76
   988
insilmaril@76
   989
\subsection{Hide links of unselected objects} \label{hidelink}
insilmaril@76
   990
Sometimes it would be useful to position a branch freely, just like a
insilmaril@76
   991
mainbranch or an image. This is possible for all
insilmaril@76
   992
branches, you can use a mainbranch and hide its connecting link to the
insilmaril@76
   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@76
   994
pointing to other maps:
insilmaril@76
   995
\begin{center}
insilmaril@76
   996
	\includegraphics[width=9cm]{images/hiddenlink.png}
insilmaril@76
   997
\end{center}
insilmaril@76
   998
To hide the link between a branch and its parent open the
insilmaril@76
   999
\ref{propwindow} and check "Hide link if object is not selected" on
insilmaril@76
  1000
"Link" tab.
insilmaril@76
  1001
insilmaril@76
  1002
insilmaril@76
  1003
\subsection{XLinks} \label{xlinks}
insilmaril@76
  1004
So far all the data in the \vym map has been treelike. Using xLinks you
insilmaril@76
  1005
can link one branch to any other, just like attaching a rope between two
insilmaril@76
  1006
branches in a real tree. This is especially useful in complex maps,
insilmaril@76
  1007
where you want to have crossreferences which can not be displayed on the same
insilmaril@76
  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@76
  1009
	\maximage{images/xlink.png}
insilmaril@76
  1010
Note that a xLink which points to a branch that is not visible (because
insilmaril@76
  1011
it is scrolled), is just shown as a little horizontal arrow. In the
insilmaril@76
  1012
screenshot above have a look at the \lq Tuesday\rq\ branch.
insilmaril@76
  1013
insilmaril@76
  1014
\subsubsection*{Create a xLink}
insilmaril@76
  1015
Choose the link mode from the modifier toolbar (by clicking the toolbar icon or pressing
insilmaril@76
  1016
\key{L}). Select the branch, where the xLink should start. Press the
insilmaril@76
  1017
modifier key \key{Ctrl} and then click on the selected branch where the
insilmaril@76
  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@76
  1019
insilmaril@76
  1020
\subsubsection*{Modify or delete a xLink}
insilmaril@76
  1021
First select a branch at either end of the xLink. Then open the context
insilmaril@76
  1022
menu and select \lq Edit xLink\rq. A submenu contains all the xLinks of
insilmaril@76
  1023
the branch (if there are any). They are named like the branches, where
insilmaril@76
  1024
they end. Choose one and the xLink dialogue opens, where you can set
insilmaril@76
  1025
colour, width and also delete the xLink.
insilmaril@76
  1026
insilmaril@76
  1027
\subsubsection*{Follow a xLink}
insilmaril@76
  1028
In a complex \vym map it sometimes comes in handy to be able to jump to the other end
insilmaril@76
  1029
of a xLink. You can do this by opening the context menu of the branch
insilmaril@76
  1030
and clicking on \lq Goto xLink\rq and selecting the xLink you want to
insilmaril@76
  1031
follow.
insilmaril@76
  1032
insilmaril@76
  1033
insilmaril@76
  1034
insilmaril@76
  1035
\subsection{Adding and removing branches}
insilmaril@76
  1036
The context menu of a branch shows some more ways to add and delete data
insilmaril@76
  1037
e.g. you can delete a branch while keeping its children. The children become
insilmaril@76
  1038
linked to the parent of the previously removed branch.
insilmaril@76
  1039
Similar branches can be inserted into existing maps. For keyboard
insilmaril@76
  1040
shortcuts also have a look at the context menu.
insilmaril@76
  1041
insilmaril@76
  1042
\subsection{Adding a whole map or a part of a map}
insilmaril@76
  1043
Select a branch where you want to add a previously saved map ({\tt
insilmaril@76
  1044
.vym})or a part of a map ({\tt .vyp}) , then open the context menu and
insilmaril@76
  1045
choose {\em Add \ra Add Map (Insert)}. For the import you can choose
insilmaril@76
  1046
between {\em Add Map (Insert)} and {\em Add Map (Replace)}: The imported
insilmaril@76
  1047
data will be added after the selected branch.
insilmaril@76
  1048
insilmaril@76
  1049
insilmaril@76
  1050
\section{\vym on Mac OS X}
insilmaril@76
  1051
\subsection{Overview}
insilmaril@76
  1052
Basically there are two ways to run \vym on Macs:
insilmaril@76
  1053
\subsubsection*{Qt Mac Edition:}
insilmaril@76
  1054
	\vym here provides the well known Mac look and feel.  \vym is
insilmaril@76
  1055
	available as Mac OS X application package in contained in a disk
insilmaril@76
  1056
	image ({\tt vym.dmg}. It has been compiled and tested in
insilmaril@76
  1057
	Mac~OS~10.4.  This package includes  runtime libraries of Qt by
insilmaril@76
  1058
	Trolltech.
insilmaril@76
  1059
	
insilmaril@76
  1060
\subsubsection*{X11 version} \vym can also be run using the Linux
insilmaril@76
  1061
version, but then menus and handling will also be those of the Linux
insilmaril@76
  1062
version e.g. The menu bar will look different. 
insilmaril@76
  1063
insilmaril@76
  1064
\subsection	{Contextmenu and special keys}
insilmaril@76
  1065
Most Macs unfortunatly just have a single mouse button. In order to show
insilmaril@76
  1066
the context menu which usually would be opened with the right mouse
insilmaril@76
  1067
button, you can click while pressing the \key{kommand}-key.
insilmaril@76
  1068
insilmaril@76
  1069
Especially on Laptops some of the keys usually used on PC keyboards seem
insilmaril@76
  1070
to be missing. The QT-Mac Edition of \vym has its own keyboard
insilmaril@76
  1071
shortcuts. To find the shortcuts just have a look at all the menu
insilmaril@76
  1072
entries, the shortcut is visible next to an entry. Toolbar buttons also
insilmaril@76
  1073
may have shortcuts, just position the mouse pointer over a button and
insilmaril@76
  1074
wait for the little help window to appear. 
insilmaril@76
  1075
insilmaril@76
  1076
\subsection {Viewing external links}
insilmaril@76
  1077
\vym on Mac uses the system call {\tt /usr/bin/open} to view links.
insilmaril@76
  1078
Mac~OS determines automatically if the link is a pdf or www page and
insilmaril@76
  1079
opens the right browser.
insilmaril@76
  1080
insilmaril@76
  1081
insilmaril@76
  1082
\newpage
insilmaril@76
  1083
insilmaril@76
  1084
\begin{appendix}
insilmaril@76
  1085
insilmaril@76
  1086
\section{\vym initialisation process and configuration}
insilmaril@76
  1087
\subsection {Settings menu}
insilmaril@76
  1088
	The {\em Settings} menu allows to configure \vym to your needs:
insilmaril@76
  1089
insilmaril@76
  1090
\subsubsection*{Set application to open PDF files} Choose a PDF
insilmaril@76
  1091
	viewer like {\tt acrobat} or {\tt konqueror} which is installed on
insilmaril@76
  1092
	your system.
insilmaril@76
  1093
insilmaril@76
  1094
\subsubsection*{Set application to open external links}
insilmaril@76
  1095
	Choose your favourite webbrowser here.
insilmaril@76
  1096
insilmaril@76
  1097
\subsubsection*{Set path for macros}
insilmaril@76
  1098
	Set the default search path for macros, which will be executed when
insilmaril@76
  1099
	you press one of the function keys. Each key corresponds to a file
insilmaril@76
  1100
	({\tt macro-1.vys..macro12.vys}) in the search path.
insilmaril@76
  1101
insilmaril@76
  1102
\subsubsection*{Set number of undo levels}
insilmaril@76
  1103
	Sets the number of undo/redo levels. The default setting is
insilmaril@76
  1104
	75~levels.
insilmaril@76
  1105
insilmaril@76
  1106
\subsubsection*{Autosave and autosave time}
insilmaril@76
  1107
	Automatic saving of modified maps can be toggled on or off. The
insilmaril@76
  1108
	autosave time is entered in seconds.
insilmaril@76
  1109
insilmaril@76
  1110
\subsubsection*{Write backup on save}
insilmaril@76
  1111
	When saving a map called {\tt example.vym}, \vym will rename the
insilmaril@76
  1112
	existing file to {\tt example.vym\~{}} before writing the {\tt
insilmaril@76
  1113
	example.vym} itself.
insilmaril@76
  1114
insilmaril@76
  1115
\subsubsection*{Edit branch after adding it}
insilmaril@76
  1116
	If set, the heading of a new branch will be edited immediatly after
insilmaril@76
  1117
	adding the branch.
insilmaril@76
  1118
insilmaril@76
  1119
\subsubsection*{Select branch after adding it}
insilmaril@76
  1120
	If set, a new branch will be selected immediatly after adding it.
insilmaril@76
  1121
	When you "brainstorm" on a given keyword, you don't want to go
insilmaril@76
  1122
	deeper and deeper into details, but keep the focus on the keyword.
insilmaril@76
  1123
	So the default setting here is to {\em not} select the freshly added
insilmaril@76
  1124
	branch.
insilmaril@76
  1125
	
insilmaril@76
  1126
\subsubsection*{Select existing heading}
insilmaril@76
  1127
	If set and you begin to edit the heading of a branch, the heading text in
insilmaril@76
  1128
	the dialog will be selected. Usefully to copy\&paste to other
insilmaril@76
  1129
	applications.
insilmaril@76
  1130
insilmaril@76
  1131
\subsubsection*{Delete key}
insilmaril@76
  1132
	If set, the \key{Delete} is enabled to, well, delete objects. This
insilmaril@76
  1133
	can be switched off to avoid confusing with the nearby
insilmaril@76
  1134
	\key{Insert}-key on PC keyboards.
insilmaril@76
  1135
insilmaril@76
  1136
\subsubsection*{Exclusive flags}
insilmaril@76
  1137
	If set, some of the standard flags can only be used exclusively,
insilmaril@76
  1138
	e.g.~the smileys.
insilmaril@76
  1139
insilmaril@76
  1140
\subsubsection*{Use hide flags}
insilmaril@76
  1141
	If set, every branch which also has the hide flag set (see
insilmaril@76
  1142
	\ref{hideexport}) will be hidden in exports.
insilmaril@76
  1143
insilmaril@76
  1144
\subsection{Configuration file}
insilmaril@76
  1145
On startup \vym will look for a configuration for user specific settings
insilmaril@76
  1146
like window positions, toolbars etc. If this file does not already
insilmaril@76
  1147
exist, it will be created. The file is located in the users home
insilmaril@76
  1148
directory. The exact position depends on the platform:
insilmaril@76
  1149
\begin{center}
insilmaril@76
  1150
\begin{tabular}{cl}
insilmaril@76
  1151
	{\bf Platform}	& {\bf Configuration file} \\ \hline
insilmaril@76
  1152
	Linux		& {\tt $\sim$/.config/InSilmaril/vym.conf  } \\
insilmaril@76
  1153
	Mac OS X	& {\tt /Users/NAME/Library/Preferences/com.insilmaril.vym.plist  } \\
insilmaril@76
  1154
\end{tabular}
insilmaril@76
  1155
\end{center}
insilmaril@76
  1156
The file can be edited manually, or on Mac~OS~X with Property List
insilmaril@76
  1157
Editor (installed with xtools).
insilmaril@76
  1158
insilmaril@76
  1159
\subsection{Path to ressources}
insilmaril@76
  1160
\vym will try to find its ressources (images, stylesheets, filters,
insilmaril@76
  1161
etc.) in the following places:
insilmaril@76
  1162
\begin{enumerate}
insilmaril@76
  1163
	\item Path given by the environment variable {\tt VYMHOME}.
insilmaril@76
  1164
	\item If called with the local option (see \ref{options} below),
insilmaril@76
  1165
	      \vym will look for its data in the current directory.
insilmaril@76
  1166
	\item {\tt /usr/share/vym}
insilmaril@76
  1167
	\item {\tt /usr/local/share/vym}
insilmaril@76
  1168
\end{enumerate}
insilmaril@76
  1169
insilmaril@76
  1170
\subsection{Command line options} \label{options}
insilmaril@76
  1171
\vym has the following options:
insilmaril@76
  1172
\begin{center}
insilmaril@76
  1173
\begin{tabular}{cccp{8cm}}\\ 
insilmaril@76
  1174
\bf Option	& \bf Comment & \bf Argument & \bf Description \\ \hline
insilmaril@76
  1175
v & version &			& Show version and codename of \vym\\
insilmaril@76
  1176
l & local	&			& Use local paths to stylesheets, translations, icons, 
insilmaril@76
  1177
                          etc. instead of system paths. Useful for testing\\
insilmaril@76
  1178
h & help	&			& Show help\\
insilmaril@76
  1179
r & run 	& filename	& Load and run script\\
insilmaril@76
  1180
q & quit	&			& Quit immediatly after startup. Useful for benchmarks.\\
insilmaril@76
  1181
\end{tabular}
insilmaril@76
  1182
\end{center}
insilmaril@76
  1183
You can also give several filenames at the commandline to let \vym open
insilmaril@76
  1184
several maps at once.
insilmaril@76
  1185
 
insilmaril@76
  1186
insilmaril@76
  1187
\section{Scripts} \label{scripts}   %FIXME
insilmaril@76
  1188
insilmaril@76
  1189
TODO: This section of the \vym manual is not complete yet, sorry.
insilmaril@76
  1190
insilmaril@76
  1191
\subsection{Example scripts}
insilmaril@76
  1192
\subsubsection{Export a set of maps}
insilmaril@76
  1193
\begin{code}
insilmaril@76
  1194
\# Simple vym script to export images of various maps simultanously
insilmaril@76
  1195
exportImage ();
insilmaril@76
  1196
\end{code}
insilmaril@76
  1197
The script above can be used to export all maps in a directory
insilmaril@76
  1198
automatically. If the script is named {\tt export-image.vys}, call \vym with
insilmaril@76
  1199
\begin{code}
insilmaril@76
  1200
\$ vym --quit --run export-image.vys *.vym
insilmaril@76
  1201
\end{code}
insilmaril@76
  1202
insilmaril@76
  1203
insilmaril@76
  1204
\section{Contributing to \vym}
insilmaril@76
  1205
So far I'd say I have written 98\% of the code on my own. No surprise,
insilmaril@76
  1206
that \vym exactly fits my own needs. Nevertheless I would like to
insilmaril@76
  1207
encourage all users of  \vym to contribute. Maybe not only with feature
insilmaril@76
  1208
requests, but also with code, new import/export filters, translations
insilmaril@76
  1209
etc. In this appendix I'll try to show how easy it is to expand the
insilmaril@76
  1210
things you can do already with \vym. I really look forward to hear from
insilmaril@76
  1211
you!
insilmaril@76
  1212
insilmaril@76
  1213
\subsection{Getting help}
insilmaril@76
  1214
insilmaril@76
  1215
\subsubsection*{Frequently asked questions}
insilmaril@76
  1216
Please refer to the FAQ available on the \vym website:
insilmaril@76
  1217
\begin{center}
insilmaril@76
  1218
\href{http://www.InSilmaril.de/vym/faq.html}{http://www.InSilmaril.de/vym/faq.html}
insilmaril@76
  1219
\end{center}
insilmaril@76
  1220
insilmaril@76
  1221
\subsubsection*{Mailinglists}
insilmaril@76
  1222
There are two mailinglists: {\tt vym-forum} is the \vym users forum to
insilmaril@76
  1223
discuss various questions, while {\tt vym-devel} is intended for people
insilmaril@76
  1224
interested in contributing to \vym. You can view the archives and
insilmaril@76
  1225
subscribe at
insilmaril@76
  1226
\begin{center}
insilmaril@76
  1227
\href{https://sourceforge.net/mail/?group_id=127802}{https://sourceforge.net/mail/?group\_id=127802}
insilmaril@76
  1228
\end{center}
insilmaril@76
  1229
insilmaril@76
  1230
\subsubsection*{Contacting the author}\label{author}
insilmaril@76
  1231
Especially for support questions please try the mailinglists first. If
insilmaril@76
  1232
everything else fails you can contact the author Uwe Drechsel at
insilmaril@76
  1233
\begin{center}
insilmaril@76
  1234
\href{mailto:vym@InSilmaril.de}{vym@InSilmaril.de}
insilmaril@76
  1235
\end{center}
insilmaril@76
  1236
insilmaril@76
  1237
insilmaril@76
  1238
insilmaril@76
  1239
\subsection{How to report bugs}
insilmaril@76
  1240
Though Sourceforge has its own bugreporting system, I'd rather prefer if
insilmaril@76
  1241
you contact me directly (see \ref{author}) or even better: You can file
insilmaril@76
  1242
a bugreport in Bugzilla, the bugtracking system of openSUSE:
insilmaril@76
  1243
\begin{center}
insilmaril@76
  1244
\href{http://en.opensuse.org/Submit_a_bug}{http://en.opensuse.org/Submit\_a\_bug}
insilmaril@76
  1245
\end{center}
insilmaril@76
  1246
I build \vym regulary for openSUSE, so you may report it against a
insilmaril@76
  1247
recent version there, even if you  use another Operating System.
insilmaril@76
  1248
Please don't forget to tell me what you are using:
insilmaril@76
  1249
\begin{itemize}
insilmaril@76
  1250
	\item the exact steps needed to reproduce the bug
insilmaril@76
  1251
	\item the version and build date of \vym (see the Help \ra About
insilmaril@76
  1252
	\vym)
insilmaril@76
  1253
	\item hardware and Operating System
insilmaril@76
  1254
\end{itemize}
insilmaril@76
  1255
insilmaril@76
  1256
\subsection{Compiling from the sources}
insilmaril@76
  1257
\subsubsection{Getting the sources} \label{getsources}
insilmaril@76
  1258
You find the latest version of \vym at the project site:
insilmaril@76
  1259
\begin{center}
insilmaril@76
  1260
\href{https://sourceforge.net/projects/vym/}{https://sourceforge.net/projects/vym/}
insilmaril@76
  1261
\end{center}
insilmaril@76
  1262
There you can check them out of the source repository (CVS):\\
insilmaril@76
  1263
insilmaril@28
  1264
\begin{verbatim}
insilmaril@76
  1265
cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/vym checkout code
insilmaril@28
  1266
\end{verbatim}
insilmaril@28
  1267
insilmaril@76
  1268
\subsubsection{The Qt toolkit}
insilmaril@76
  1269
Qt is C++ toolkit for multiplatform GUI and application development. It
insilmaril@76
  1270
provides single-source portability across MS~Windows, Mac~OS~X, Linux
insilmaril@76
  1271
and all major commercial Unix variants. Qt is also available for
insilmaril@76
  1272
embedded devices. Qt is a Trolltech product. For more information see 
insilmaril@76
  1273
\begin{center}
insilmaril@76
  1274
\href{http://www.trolltech.com/qt/}{www.trolltech.com/qt} 
insilmaril@76
  1275
\end{center}
insilmaril@76
  1276
insilmaril@76
  1277
insilmaril@76
  1278
\subsubsection{Compiling \vym }
insilmaril@76
  1279
Make sure you have installed your Qt environment properly, see the Qt
insilmaril@76
  1280
documentation for details. You need to have the Qt command {\tt qmake}
insilmaril@76
  1281
in your {\tt PATH}-environment, then run
insilmaril@76
  1282
\begin{code}
insilmaril@76
  1283
\$ qmake
insilmaril@76
  1284
$ make  
insilmaril@76
  1285
$ make install
insilmaril@76
  1286
\end{code}
insilmaril@76
  1287
The last command {\tt make install} needs root-permissions. Of course it
insilmaril@76
  1288
may be omitted, if you just want to test \vym.
insilmaril@76
  1289
insilmaril@76
  1290
%\subsubsection*{Compiling \vym on Macs}
insilmaril@76
  1291
%FIXME
insilmaril@76
  1292
insilmaril@76
  1293
\subsection{\vym file format} \label{fileformat}
insilmaril@76
  1294
\vym maps usually have the suffix "{\tt .vym}" and represent a
insilmaril@76
  1295
compressed archive of data. If you want to have a
insilmaril@76
  1296
closer look into the data structure map called "mapname.vym", 
insilmaril@76
  1297
just uncompress the map manually using
insilmaril@76
  1298
\begin{code}
insilmaril@76
  1299
\$ unzip mapname.vym
insilmaril@76
  1300
\end{code}
insilmaril@76
  1301
This will create directories named {\tt images} and {\tt flags} in your
insilmaril@76
  1302
current directory and also the map itself, usually named {\tt
insilmaril@76
  1303
mapname.xml}.
insilmaril@76
  1304
The XML structure of \vym is pretty self explaining, just have a look at
insilmaril@76
  1305
{\tt mapname.xml}.
insilmaril@76
  1306
insilmaril@76
  1307
This XML file can be loaded directly into \vym, it does not have to be
insilmaril@76
  1308
compressed. If you want to compress all the data yourself, use
insilmaril@76
  1309
\begin{code}
insilmaril@76
  1310
\$ zip -r mapname.vym .
insilmaril@76
  1311
\end{code}
insilmaril@76
  1312
to compress all data in your current directory.
insilmaril@76
  1313
insilmaril@76
  1314
\subsection{New features}
insilmaril@76
  1315
There are lots of features which might find their way into \vym.
insilmaril@76
  1316
Together with \vym you should have received a directory with several
insilmaril@76
  1317
example maps. You find them by clicking Help \ra Open~vym~example~maps.
insilmaril@76
  1318
There you will find the map {\tt vym-projectplan.vym}. It lists quite a
insilmaril@76
  1319
lot of things to be done in future. If you have more ideas, contact the
insilmaril@76
  1320
development team at {\tt vym-devel@lists.sourceforge.net}.
insilmaril@76
  1321
insilmaril@76
  1322
insilmaril@76
  1323
\subsection{New languages support}
insilmaril@76
  1324
In order to add a new language to \vym you need 
insilmaril@76
  1325
the sources (see \ref{getsources}) and
insilmaril@76
  1326
an installation of Trolltechs QT. A part of QT are the development
insilmaril@76
  1327
tools, from those tools especially the translation tool "Linguist" is
insilmaril@76
  1328
needed. 
insilmaril@76
  1329
insilmaril@76
  1330
In some Linux distributions the development tools are in an extra package, e.g. on SUSE LINUX you should have installed:
insilmaril@76
  1331
\begin{code}
insilmaril@76
  1332
libqt4-devel.rpm
insilmaril@76
  1333
libqt4-devel-doc.rpm
insilmaril@76
  1334
libqt4-devel-tools.rpm
insilmaril@76
  1335
\end{code}
insilmaril@76
  1336
If you don't have QT in your system, you can get it from 
insilmaril@76
  1337
	\href{http://www.trolltech.com}{http://www.trolltech.com} Once you
insilmaril@76
  1338
	are able to compile vym yourself, you can translate the text in vym
insilmaril@76
  1339
	itself by performing the following steps:
insilmaril@76
  1340
\begin{itemize}
insilmaril@76
  1341
	\item Let's assume now your encoding is "NEW" instead of for example
insilmaril@76
  1342
	"de" for german or "en" for english
insilmaril@76
  1343
	
insilmaril@76
  1344
	\item Copy the file {\tt lang/vym\_en.ts} to l{\tt ang/vym\_NEW.ts} (The code
insilmaril@76
  1345
	itself contains the english version.)
insilmaril@76
  1346
		
insilmaril@76
  1347
	\item Add {\tt lang/vym\_NEW.ts} to the TRANSLATIONS section of vym.pro
insilmaril@76
  1348
insilmaril@76
  1349
	\item Run Linguist on {\tt vym\_NEW.ts} and do the translation
insilmaril@76
  1350
insilmaril@76
  1351
	\item Run {\tt lrelease} to create {\tt vym\_NEW.qm}
insilmaril@76
  1352
insilmaril@76
  1353
	\item Do a make install to install the new vym and check your translation
insilmaril@76
  1354
\end{itemize}
insilmaril@76
  1355
insilmaril@76
  1356
If you feel brave, you can also translate the manual. It is written in
insilmaril@76
  1357
LaTeX, you just have to change the file tex/vym.tex. (Linguist and QT
insilmaril@76
  1358
are not needed, but it is useful to know how to work with LaTeX and esp.
insilmaril@76
  1359
pdflatex to create the PDF.) 
insilmaril@76
  1360
insilmaril@76
  1361
Please mail me every translation you have done. I can also give you a
insilmaril@76
  1362
developer access to the project, if you want to provide translations
insilmaril@76
  1363
regulary.  
insilmaril@76
  1364
insilmaril@76
  1365
\subsection{New export/import filters}
insilmaril@76
  1366
\vym supports various kinds of filters. Data can be written directly,
insilmaril@76
  1367
inserted into templates or it can be written as XML data and then
insilmaril@76
  1368
processed by XSL transformations. 
insilmaril@76
  1369
insilmaril@76
  1370
Most of the import/export functionality is available in the classes
insilmaril@76
  1371
ImportBase and ExportBase and subclasses. All of them can be found in
insilmaril@76
  1372
{\tt imports.h} and {\tt exports.h}.
insilmaril@76
  1373
insilmaril@76
  1374
\subsubsection*{Direct import/export}
insilmaril@76
  1375
An example for a direct export is the XML export. This method touches
insilmaril@76
  1376
the implementation of nearly every object of \vym, so whenever possible
insilmaril@76
  1377
you should better use a XSL transformation instead.
insilmaril@76
  1378
insilmaril@76
  1379
If you still want to know how it is done, start looking at 
insilmaril@76
  1380
{\tt MapEditor::saveToDir} in {\tt mapeditor.cpp}.
insilmaril@76
  1381
insilmaril@76
  1382
\subsubsection*{Templates}
insilmaril@76
  1383
Templates have been introduced to export to opendoc format used e.g. by
insilmaril@76
  1384
Open~Office. While I read the spec ($>$ 500 pages) about the format\footnote{
insilmaril@76
  1385
\href{http://www.oasis-open.org/}{http://www.oasis-open.org/}}\ 
insilmaril@76
  1386
I had the feeling that I did not want to write the export from scratch. 
insilmaril@76
  1387
It would be too complex to adapt the styles to your own wishes, e.g. the
insilmaril@76
  1388
layout.
insilmaril@76
  1389
insilmaril@76
  1390
Instead I analyzed existing Open~Office documents. I found out that
insilmaril@76
  1391
there are lots of redundant bits of information in a standard
insilmaril@76
  1392
presentation, for example each list item is contained in its own list.
insilmaril@76
  1393
In the end I came up with the default presentation style, which still
insilmaril@76
  1394
could be simplified, just in case you have free time\ldots
insilmaril@76
  1395
insilmaril@76
  1396
The existing templates are still work in progress, before you spend too
insilmaril@76
  1397
much time developing your own style, please contact me.  Basically the
insilmaril@76
  1398
following steps are needed to build your own style:
insilmaril@76
  1399
\begin{enumerate}
insilmaril@76
  1400
	\item Create an example in Open Office. Use a title, authors name,
insilmaril@76
  1401
	page heading etc.\ which you can easily grep for in the output file.
insilmaril@76
  1402
	
insilmaril@76
  1403
	\item Unzip  the Open Office document into a directory.
insilmaril@76
  1404
insilmaril@76
  1405
	\item The main file is called {\tt content.xml}. All data is in one
insilmaril@76
  1406
	single line. You can split the XML tags using the script {\tt
insilmaril@76
  1407
	scripts/niceXML}, which is part of the \vym distribution.
insilmaril@76
  1408
insilmaril@76
  1409
	\item Copy the output of {\tt niceXML} to {\tt
insilmaril@76
  1410
	content-template.xml}.
insilmaril@76
  1411
insilmaril@76
  1412
	\item Looking closer you will find lots of unused definitions, for
insilmaril@76
  1413
	example of styles. You can delete or simply ignore them.
insilmaril@76
  1414
insilmaril@76
  1415
	\item Try to find your title, authors name. \vym will replace the
insilmaril@76
  1416
	following strings while exporting:
insilmaril@76
  1417
	\begin{center}
insilmaril@76
  1418
	\begin{tabular}{lp{4cm}}
insilmaril@76
  1419
		{\tt <!-- INSERT TITLE -->}		& title of map \\
insilmaril@76
  1420
		{\tt <!-- INSERT AUTHOR-->	}	& author \\
insilmaril@76
  1421
		{\tt <!-- INSERT COMMENT -->}	& comment \\
insilmaril@76
  1422
		{\tt <!-- INSERT PAGES-->}		& content of map \\
insilmaril@76
  1423
	\end{tabular}
insilmaril@76
  1424
	\end{center}
insilmaril@76
  1425
	The content itself is generated in a similar way by inserting lists
insilmaril@76
  1426
	into {\tt page-template}. Here the following substitutions are made:
insilmaril@76
  1427
	\begin{center}
insilmaril@76
  1428
	\begin{tabular}{lp{7cm}}
insilmaril@76
  1429
		{\tt <!-- INSERT PAGE HEADING-->}		& heading of a page
insilmaril@76
  1430
		(mainbranch or child of mainbranch, depending on the use of
insilmaril@76
  1431
		sections) \\
insilmaril@76
  1432
		{\tt <!-- INSERT LIST -->	}	& all children of the branch above \\
insilmaril@76
  1433
	\end{tabular}
insilmaril@76
  1434
	\end{center}
insilmaril@76
  1435
\end{enumerate}
insilmaril@76
  1436
Currently images are exported and notes just will appear as text
insilmaril@76
  1437
without formatting and colours.
insilmaril@76
  1438
insilmaril@76
  1439
insilmaril@76
  1440
insilmaril@76
  1441
insilmaril@76
  1442
\subsubsection*{XSL Transformation}
insilmaril@76
  1443
\vym uses XSL transformations while exporting (e.g. XHTML) and importing
insilmaril@76
  1444
data (e.g. KDE bookmarks). There is a little code needed to provide the
insilmaril@76
  1445
GUI, the rest is done using the {\tt .xsl} stylesheet and calling the
insilmaril@76
  1446
{\tt xsltproc} processor, which is part of libxslt, the XSLT
insilmaril@76
  1447
C  library  for  GNOME. 
insilmaril@76
  1448
insilmaril@76
  1449
\end{appendix}
insilmaril@76
  1450
\end{document}
insilmaril@28
  1451
insilmaril@28
  1452
%TODO
insilmaril@28
  1453
%\subsubsection{Menus}
insilmaril@28
  1454
%\subsubsection{Keyboard shortcuts}
insilmaril@28
  1455
%Where does vym save its settings? -> ~/.qt/vymrc
insilmaril@28
  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@76
  1478
% vymlink
insilmaril@76
  1479
% xlink
insilmaril@76
  1480
% modMode
insilmaril@76
  1481
% context menu
insilmaril@76
  1482
% Mac OS X
insilmaril@28
  1483
insilmaril@28
  1484
insilmaril@28
  1485
insilmaril@76
  1486
\end{document}