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