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