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