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