1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/tex/vym.tex Thu Jul 27 14:07:11 2006 +0000
1.3 @@ -0,0 +1,1290 @@
1.4 +\documentclass{article}
1.5 +\usepackage{a4}
1.6 +\usepackage[latin1]{inputenc}
1.7 +\usepackage{verbatim}
1.8 +\usepackage{hyperref}
1.9 +\usepackage{graphicx}
1.10 +\usepackage{longtable}
1.11 +
1.12 +
1.13 +%\input{udmath}
1.14 +
1.15 +
1.16 +\hypersetup{bookmarks, bookmarksopen,
1.17 + pdftitle={VYM - a tool for visual thinking },
1.18 + pdfauthor={Uwe Drechsel},
1.19 + pdfsubject={map},
1.20 + pdfkeywords={map, tool},
1.21 + pdfpagemode={UseOutlines},
1.22 + bookmarksopenlevel={1},
1.23 + colorlinks={true},
1.24 + linkcolor={blue},
1.25 + urlcolor={green},
1.26 + citecolor={red}}
1.27 +
1.28 +
1.29 +\newcommand{\vym}{{\sc vym }}
1.30 +\newcommand{\ra}{$\longrightarrow$}
1.31 +\newcommand{\la}{$\longleftarrow$}
1.32 +\newcommand{\ua}{$\uparrow$}
1.33 +\newcommand{\da}{$\downarrow$}
1.34 +\newcommand{\key}[1]{[#1]}
1.35 +
1.36 +\begin{document}
1.37 +\title{
1.38 + \includegraphics[width=8cm]{vym-logo-new.png}
1.39 + \\
1.40 +VYM \\ -- \\View Your Mind\\ {\small Version 1.8.0}}
1.41 +\author{\textcopyright Uwe Drechsel }
1.42 +
1.43 +
1.44 +\maketitle
1.45 +
1.46 +\newpage
1.47 +
1.48 +\tableofcontents
1.49 +
1.50 +\newpage
1.51 +
1.52 +\section{Introduction}
1.53 +\subsection{What is a \vym map?}
1.54 +A \vym map (in short words {\em map}) is a tree like structure:
1.55 +\begin{center}
1.56 + \includegraphics[width=12cm]{example1.png}
1.57 +\end{center}
1.58 +Such maps can be drawn by hand on a paper or flip chart and help to
1.59 +structure your thoughts. While a tree like structure like above can be
1.60 +drawn manually \vym offers much more features to work with such maps.
1.61 +\vym is not another drawing software, but a tool to store and modify
1.62 +information in an intuitive way. For example you can reorder parts of
1.63 +the map by pressing a key or add various information like a complete
1.64 +email by a simple mouse click.
1.65 +
1.66 +Once you have finished collecting and organizing your ideas, you can
1.67 +easily generate for example a presentation in Open~Office based on a
1.68 +map.
1.69 +
1.70 +\subsection{Why should I use maps? Time, Space and your Brain.}
1.71 +\subsubsection*{Space}
1.72 +A map can concentrate a very complex content on little space e.g. a
1.73 +piece of paper. It helps to use both sides of your brain: the logical
1.74 +side and also your creative side (e.g. by using pictures, colors and
1.75 +keywords in a map, so called {\em anchors}). It is a technique to
1.76 +organize the way you think: It can help you by developing, sorting and
1.77 +memorizing your thoughts.
1.78 +
1.79 +\subsubsection*{Time}
1.80 +Because you just use keywords and drawings, it is much faster than good
1.81 +old fashioned notes. Your brain memorizes things by associating them to
1.82 +other things -- a map makes use of those connections and stimulates
1.83 +new asccociations.
1.84 +
1.85 +
1.86 +\subsubsection*{Your Brain}
1.87 +In 1960 the Prof. {\sc Roger Sperry} discovered that both hemispheres
1.88 +of the human brain have different tasks (of course both of them
1.89 +basically {\em can} do the same):
1.90 +\begin{center}
1.91 +\begin{tabular}{|p{5.5cm}|p{5.5cm}|} \hline
1.92 + Left side & Right side \\ \hline
1.93 + \begin{itemize}
1.94 + \item verbal speech and writing
1.95 + \item numbers
1.96 + \item logical thinking
1.97 + \item analyzing and details
1.98 + \item science
1.99 + \item linear thinking
1.100 + \item concept of time
1.101 + \end{itemize} &
1.102 + \begin{itemize}
1.103 + \item body language
1.104 + \item visual thinking, day dreams
1.105 + \item intuition and emotion
1.106 + \item overview of things
1.107 + \item creativity
1.108 + \item art, music, dancing
1.109 + \item non-linear thinking, connecting things
1.110 + \item spatial awareness
1.111 + \end{itemize} \\ \hline
1.112 +\end{tabular}
1.113 +\end{center}
1.114 +In our science oriented society we have learned to mainly rely on our
1.115 +left side of the brain, the "rational" one. In other cultures,
1.116 +especially like the native americans and other "old" cultures, the right
1.117 +side is much more important. Maps are just one way to stimulate the
1.118 +other side and make use of additional ressources we all have.
1.119 +
1.120 +
1.121 +\subsection{Where could I use a map?}
1.122 +Here are some examples, how you can use those maps
1.123 +\begin{itemize}
1.124 + \item to prepare articles, papers, books, talks, \ldots
1.125 + \item to sort complex data
1.126 + \item to memorize facts, persons, vocabulary, \ldots
1.127 + \item to sort emails, files and bookmarks on your computer
1.128 + \item to moderate conferences
1.129 +\end{itemize}
1.130 +
1.131 +\subsection{What you shouldn't do with a map...}
1.132 +A map drawn by somebody shows the way the author thinks. There is
1.133 +no right or wrong in the way it is drawn, so there is no way to criticize
1.134 +it. "It is, what it is" ({\sc F.~Lehmann}).
1.135 +
1.136 +%\section{Tutorials}
1.137 +%TODO
1.138 +
1.139 +\subsection{Internet Ressources}
1.140 +A good starting point to learn more about maps in general is Wikipedia:
1.141 +\begin{itemize}
1.142 + \item English:
1.143 + \href{http://en.wikipedia.org/wiki/Mind_map}{http://en.wikipedia.org/wiki/Mind\_map}
1.144 + \item German:
1.145 + \href{http://de.wikipedia.org/wiki/Mindmap}{http://de.wikipedia.org/wiki/Mindmap}
1.146 +\end{itemize}
1.147 +
1.148 +
1.149 +
1.150 +
1.151 +\section{Concept of \vym}
1.152 +%TODO may add a general introduction here...
1.153 +\subsection{Windows: mapeditor and noteeditor}
1.154 +\vym uses two windows: an editor for the map itself and another one for
1.155 +notes, which are part of the map. Let's call them {\em mapeditor} and
1.156 +{\em noteeditor}:
1.157 +\begin{center}
1.158 + \includegraphics[width=8cm]{windows.png}
1.159 +\end{center}
1.160 +Usually you will work in the {\em mapeditor} by just adding new
1.161 +branches, moving around and reordering them. The various ways to do this
1.162 +will be explained in \ref{mapeditor}. You can store additional
1.163 +information e.g. the content of a email easily in a {\em branch}: Just
1.164 +type or copy\&paste it into the {\em noteeditor}. Working with notes is
1.165 +explained in \ref{noteeditor}
1.166 +
1.167 +\subsection{Menus and Context menus}
1.168 +On top of each window you find the menubar. The options you find there
1.169 +are similar to those you are used from other applications. Note that
1.170 +many (and even more) options are availabe via {\em context menus}. Those
1.171 +are available if you right-click onto an object in a map (on Mac~OS~X
1.172 +Command-Click).
1.173 +
1.174 +\subsection{Toolbars}
1.175 +The toolbars in the mainwindows give quick access to many functions and
1.176 +also visualize the state of an object. For example a part of of the map
1.177 +can be hidden when the map is exported into an Open~Office presentation.
1.178 +To show this the branch in the map will have a little cloud symbol,
1.179 +which is also "switched on" in the toolbar.
1.180 +
1.181 +Note that you can reposition all toolbars by simply grabbing them. For
1.182 +example you can move the flags-toolbar from its original horizontal
1.183 +position on top of the mapeditor to a vertical position on the right
1.184 +side. You can even detach it and make it "float" separate from the other
1.185 +windows. Or just insert it again at its original position.
1.186 +
1.187 +\subsection{Maps}
1.188 +The map itself has always a {\em mapcenter}. The
1.189 +mapcenter has {\em branches} just like the trunk of a tree. Each branch
1.190 +in turn may have branches again.
1.191 +\begin{center}
1.192 + \includegraphics[width=10cm]{branches.png}
1.193 +\end{center}
1.194 +We will call a branch directly connected to the mapcenter a {\em
1.195 +mainbranch}, because it determines the position of all its child
1.196 +branches.
1.197 +
1.198 +The mapcenter and the branches all have a {\em heading}. This is the
1.199 +text you see in the mapeditor. Usually it should just be one or a few
1.200 +words, so that one can easily keep track of the whole map.
1.201 +
1.202 +
1.203 +In the toolbar above the mapeditor you see various symbols.
1.204 +\begin{center}
1.205 + \includegraphics[width=8cm]{default-flags.png}
1.206 +\end{center}
1.207 +These are called {\em flags} and can be used to mark branches in the
1.208 +map, e.g. if something is important or questionable.
1.209 +There are also more flags set by \vym automatically to show additional
1.210 +information, e.g. when a exists for a particular branch.
1.211 +
1.212 +By default some of these flags are set exclusively e.g. when the
1.213 +"thumb-up" flag is set, then the "thumb down" is unset and vice
1.214 +versa. You can change this default behaviour in the settings menu.
1.215 +
1.216 +%TODO add info about toolbars e.g. undo/redo, ...
1.217 +
1.218 +\section{Mapeditor} \label {mapeditor}
1.219 +\subsection{Start a new map}
1.220 +After \vym is started two windows will open: the mapeditor and the
1.221 +noteditor. Usually you will work in both windows, but at the moment we
1.222 +will just need the mapeditor.
1.223 +
1.224 +Select the mapcenter "New map" in the middle of the mapeditor by
1.225 +left-clicking with the mouse. It will turn yellow to show that is
1.226 +selected. There are several ways to add a new branch to the center:
1.227 +\begin{itemize}
1.228 + \item Using the mouse: Open the context meny by clicking with the
1.229 + right mouse button (CTRL-Click on Mac) onto the
1.230 + mapcenter and choose Add \ra Add as child
1.231 + \item Press \key{Ins} or \key{A}
1.232 +\end{itemize}
1.233 +A new branch will appear and you will be able to type the heading of the
1.234 +branch. Finish adding the new branch by pressing \key{Enter}.
1.235 +%tipp
1.236 +Sometimes it comes handy to add a new branch above or below the current
1.237 +one. Use \key{Ins} together with \key{Shift} or \key{Ctrl}. It is also
1.238 +possible to add a branch in such a way, that the current selection
1.239 +becomes the child of the new branch, which is like inserting it {\em
1.240 +before} the selection. This can be done using the context menu.
1.241 +
1.242 +\subsection{Navigate through a map}
1.243 +\subsubsection*{Select branches}
1.244 +To select branches you can use the left button of your mouse or also the
1.245 +arrow keys. Depending on the {\em orientation} of a branch type
1.246 +\key{\la} or \key{\ra} to get nearer to the mapcenter or deeper
1.247 +down into the branches. Within a set of branches, let's call them a
1.248 +{\em subtree}, you can use \key{\ua} and \key{\da} to go up and down. You can
1.249 +also use \key{Pos1} and \key{End} to select the first and last branch.
1.250 +
1.251 +
1.252 +\subsubsection*{Zoom a map}
1.253 +While adding more and more branches the size of the map may become
1.254 +bigger than the mapeditor window. You can use the scrollbars on the
1.255 +right and the bottom of your mapeditor window to scroll, but it is
1.256 +easier to just scroll using the left mouse button: Click onto the {\em
1.257 +canvas} itself, the empty space somewhere between the branches. The
1.258 +mouse pointer will change from an arrow to a hand, now move the visible
1.259 +part of the map to show the desired part.
1.260 +
1.261 +If you select branches using the arrow keys, the map will scroll
1.262 +to ensure that the selected branch is always visible.
1.263 +
1.264 +Working with huge maps, the {\em zoom}-function comes in handy: You can
1.265 +use
1.266 +\begin{itemize}
1.267 + \item from the menu View \ra Zoom
1.268 + \item the toolbar buttons
1.269 + \begin{center}
1.270 + \includegraphics[width=3cm]{zoom-buttons.png}
1.271 + \end{center}
1.272 +\end{itemize}
1.273 +The crossed magnifying lens resets the zoomed view to its original size.
1.274 +
1.275 +
1.276 +\subsubsection*{Find Function} \label{findwindow}
1.277 +With huge maps there is the need to have a
1.278 +find function. Choose Edit \ra Find to open the Find Window:
1.279 +\begin{center}
1.280 + \includegraphics[width=6cm]{find-window.png}
1.281 +\end{center}
1.282 +The text you enter here will be searched in all the headings and also in
1.283 +notes. Everytime you press the "Find"-button it will look for the next
1.284 +occurence, which then will be selected automatically. If the search
1.285 +fails, there will appear a short message "Nothing found" or a few
1.286 +seconds in the {\em statusbar} on the bottom of the mapeditor.
1.287 +
1.288 +\subsubsection*{Keep the overview -- scroll a part of the map}
1.289 +A very big subtree of a map e.g. a branch with hundreds of childs makes
1.290 +it very hard to keep an overview over the whole map. You can hide all
1.291 +the childs of a branch by {\em scrolling} it -- this function is also
1.292 +often called {\em folding}. Think of the whole subtree as painted onto a
1.293 +big newspaper. You can scroll the paper to a small roll, leaving just
1.294 +the headline readable.
1.295 +
1.296 +To scroll or unscroll a branch and its childs, press the
1.297 +\begin{itemize}
1.298 + \item \key{Scroll} key or \key{S}
1.299 + \item press the middle-mouse button or
1.300 + \item choose the little scroll from the toolbar.
1.301 +\end{itemize}
1.302 +If you select parts of a scrolled branch e.g. using the find function or
1.303 +by using the arrow-keys, it will unscroll temporary. This is shown as a
1.304 +scroll with a little hour glass. If the temporary unscrolled part is not
1.305 +longer needed, it will be hidden again automatically. It is also
1.306 +possible to unscroll all branches using "Edit\ra Unscroll all scrolled
1.307 +branches".
1.308 +
1.309 +You can also hide parts of the map while exporting it e.g. to a webpage
1.310 +or a presentation, see \ref{hideexport} for details.
1.311 +
1.312 +\subsection{Modify and move branches}
1.313 +\subsubsection*{Modify the heading}
1.314 +You can edit the heading by selecting the branch and then
1.315 +\begin{itemize}
1.316 + \item pressing \key{Enter}
1.317 + \item double-clicking with left mouse.
1.318 +\end{itemize}
1.319 +Just type the new heading (or edit the old one) and press \key{Enter}.
1.320 +
1.321 +\subsubsection*{Move a branch}
1.322 +The easiest way to move a branch is to select it with left-mouse and
1.323 +drag it to the destination while keeping the mouse button pressed.
1.324 +Depending on the branch it will be
1.325 +\begin{itemize}
1.326 + \item moved to the destination or
1.327 + \item {\em linked} to a new {\em parent} (mapcenter or branch)
1.328 +\end{itemize}
1.329 +If you drag the branch over another one or over the mapcenter, you will
1.330 +notice that the link connecting it to the old parent will be changed to
1.331 +lead to the new parent which is now under your mousepointer.
1.332 +If you release the button now, the branch will be relinked.
1.333 +
1.334 +If you release the button in the middle of nowhere, the result will
1.335 +depend on the type of branch you are releasing:
1.336 +\begin{itemize}
1.337 + \item A mainbranch is directly connected to the mapcenter.
1.338 + It will stay on its new position.
1.339 + \item An ordinary branch will "jump" back to its original position.
1.340 +\end{itemize}
1.341 +Thus you can easily rearrange the layout of the mainbranches to avoid
1.342 +overlapping of their subtrees.
1.343 +There is another convenient way to move branches, especially if you want
1.344 +to {\em reorder} a subtree: You can move a branch up or down in a
1.345 +subtree by
1.346 +\begin{itemize}
1.347 + \item pressing \key{\ua} and \key {\da}
1.348 + \item selecting Edit \ra Move branch
1.349 + \item clicking on the toolbar buttons:
1.350 + \begin{center}
1.351 + \includegraphics[width=1.5cm]{move-buttons.png}
1.352 + \end{center}
1.353 +\end{itemize}
1.354 +%tipp
1.355 +There is yet another way to move branches: If you press \key{Shift} or
1.356 +\key{Ctrl} while moving with the mouse, the branch will be added above
1.357 +or below the one the mouse pointer is over. This helps also to reorder a
1.358 +map.
1.359 +
1.360 +\subsection{The right side of your brain - colors and images}
1.361 +\subsubsection*{Change color of a heading}
1.362 +You can also use colors to put more information into a map, e.g. use
1.363 +red, green and more colors to prioritize tasks. Again you can
1.364 +\begin{itemize}
1.365 + \item use the menu and choose e.g Format \rq Set Color
1.366 + \item use the toolbar
1.367 + \begin{center}
1.368 + \includegraphics[width=3cm]{color-buttons.png}
1.369 + \end{center}
1.370 +\end{itemize}
1.371 +The first button (black in the graphic above) shows the actual color.
1.372 +Clicking on it let's you choose another color. You can also "pick"
1.373 +another color by selecting a branch with the desired color and using the
1.374 +"pick color" button. Both of the buttons showing a bucket actually put
1.375 +the current color to the selected branch. While the first one just
1.376 +colors the heading of the selection, the last one also colors all the
1.377 +childs of the selected branch.
1.378 +
1.379 +%tipp
1.380 +A very useful function is the "copy color" using the mouse: Select the
1.381 +branch which should get the new color, then press \key{Ctrl} and
1.382 +simultanously click with left-mouse on another branch to copy its color
1.383 +to the first one. Here the childs of the selection also will get the new
1.384 +color, if you just want to color the selection itself, additionally
1.385 +press \key{Shift}.
1.386 +
1.387 +\subsubsection*{Use flags}
1.388 +\vym provides various flags. You see them in the toolbar on top of the
1.389 +mapeditor window. (Note: Like all toolbars you can also move them to the
1.390 +left or the right side of the window or even detach them. Just grab the
1.391 +very left "dotted" part of the toolbar with your left-mouse button.)
1.392 +\begin{center}
1.393 + \includegraphics[width=8cm]{default-flags.png}
1.394 +\end{center}
1.395 +If you have a branch selected, you can set any number of flags by
1.396 +clicking them in the toolbar. The toolbar buttons change their state and
1.397 +always reflect the flags set in the selected branch.
1.398 +
1.399 +Presently \vym uses two kinds of flags: {\em System Flags} and {\em
1.400 +Standard Flags}. The standard flags are those shown in the toolbar.
1.401 +System flags are set by \vym to indicate e.g. that there is additional
1.402 +information in a note (more on this in \ref{noteeditor}). Later versions
1.403 +of \vym may have another kind of flags, which may be edited by the user.
1.404 +
1.405 +\subsubsection*{Images}
1.406 +The easiest way to add an image to a branch is by dragging it e.g. from a
1.407 +webbrowser to the mapeditor while a branch is selected there.
1.408 +
1.409 +You can also add a image to a branch by opening the context menu of the
1.410 +branch choose "Add Image". A
1.411 +dialog window lets you choose the image to load.
1.412 +\footnote{Supported image types are: PNG, BMP, XBM, XPM and PNM. It may
1.413 + also support JPEG, MNG and GIF, if specially configured during
1.414 + compilation (as done when \vym is part of SUSE LINUX).}
1.415 +While an image is selected in the dialog, you can see a preview of the
1.416 +image. It is also possible to select multiple images.
1.417 +
1.418 +You can position the image anywhere you want, just drag it with left
1.419 +mouse. To relink it to another branch, press \key{Shift} while moving
1.420 +it. To delete it, press \key{Del}.
1.421 +
1.422 +If you right-click onto an image, a context menu will open which let's
1.423 +you first choose one of several image formats. Then a file dialog opens
1.424 +to save the image. Hint: This is used to "export" the image, it will be
1.425 +saved anyway in the map itself! You can also cut and
1.426 +copy images, but it is not possible to add objects to an image\footnote{
1.427 + Images are regarded as "extra feature". It would make working with
1.428 + the map much more complex if e.g. images could be linked to images.}
1.429 +
1.430 +The option \lq{\bf Use for export} \rq controls the output of exports
1.431 +e.g. to HTML: If set to no, the image won't appear in the {\em text}
1.432 +part of the output. This is useful for large images or if images are
1.433 +used as a kind of frame e.g. the famous cloud symbol around a part of
1.434 +the map. Those shouldn't appear in the middle of the text.
1.435 +
1.436 +At the moment image support is preliminary: Images will be saved
1.437 +together with all the other data of a map in the {\tt .vym}-file.
1.438 +Later versions will include more functionality like resizing the images,
1.439 +changing its z-value (put it into background) etc.
1.440 +
1.441 +\subsubsection*{Frames}
1.442 +A frame can be added to a branch by clicking with the
1.443 +right-mouse button. A context menu will open, where you can choose the
1.444 +frame. At the moment just a rectangle resp. "No Frame" will be offered,
1.445 +nevertheless you can use images as frames. Have a look at the demo map
1.446 +{\tt todo.vym} as an example, where the mapcenter is a cloud. You can
1.447 +use an external drawing program like {\tt gimp} to create an image,
1.448 +preferable with an transparency channel, so that you can design frames
1.449 +which don't use a rectangular borderline, just like the cloud.
1.450 +
1.451 +
1.452 +\subsection{Background design}
1.453 +The design of the background of a map and also of the links connecting
1.454 +various parts of the map can be changed by
1.455 +\begin{itemize}
1.456 + \item Selecting Format from the menu
1.457 + \item Right clicking onto the canvas, which will open a context menu
1.458 +\end{itemize}
1.459 +
1.460 +\subsubsection*{Background color}
1.461 +The color is set (and also displayed) as "Set background color".
1.462 +
1.463 +\subsubsection*{Link color}
1.464 +Links connecting branches can be colored in one of the following ways:
1.465 +\begin{itemize}
1.466 + \item use the color of the heading of the branch the links is
1.467 + \item use {\em one} color for all links. The default color is blue.
1.468 + leading to.
1.469 +\end{itemize}
1.470 +The latter can be set with "Set link color". Check or uncheck the "Use
1.471 +color of heading for link" option to choose one of the two designs for
1.472 +your map.
1.473 +
1.474 +\subsubsection*{Link style}
1.475 +\vym offers four different styles for the appearences of links:
1.476 +\begin{itemize}
1.477 + \item Line
1.478 + \item Parabel
1.479 + \item Thick Line
1.480 + \item Thick Parabel
1.481 +\end{itemize}
1.482 +The "thick" styles only draw links starting at mapcenter thick, the rest
1.483 +of the map is always painted "thin".
1.484 +
1.485 +
1.486 +\subsection{Links to other documents and webpages}
1.487 +\vym supports two kind of external links:
1.488 +\begin{itemize}
1.489 + \item Document, which will be opened in an external webbrowser
1.490 + \item \vym map, which will be opened in \vym itself
1.491 +\end{itemize}
1.492 +In addition to the external links there also internal ones, leading from one
1.493 +branch in a map toanother one. Those are called {\em XLinks} and are explained
1.494 +in section~\ref{xlinks}.
1.495 +
1.496 +\subsubsection*{Webbrowser}
1.497 +Modern Webbrowsers like {\tt konqueror} are able to display various
1.498 +types of files, both local or in the internet. To enter the URL of
1.499 +any document, right-click onto a branch or use the Edit Menu
1.500 +and choose "Edit URL". Enter the path to your document (or copy and
1.501 +paste it from your browser). Examples for valid paths are:
1.502 +\begin{verbatim}
1.503 + http://www.insilmaril.de/vym/index.html
1.504 + file:/usr/share/doc/packages/vym/doc/vym.pdf
1.505 +\end{verbatim}
1.506 +If an URL was entered, a little globe will appear in the branch. By
1.507 +clicking on the globe in the toolbar or the context menu an external
1.508 +browser\footnote{
1.509 + The browser can be changed in the Settings Menu.}
1.510 +will be started.
1.511 +\begin{center}
1.512 + \includegraphics[width=0.5cm]{flag-url.png}
1.513 +\end{center}
1.514 +For more information on working with bookmarks and webbrowsers see
1.515 +section \ref{bookmarks}.
1.516 +
1.517 +
1.518 +\subsubsection*{\vym map}
1.519 +To link to to another map right click on a branch or choose "Edit \ra
1.520 +Enter \vym link". A file dialog opens where you can choose the map. A
1.521 +branch with a link is marked with
1.522 +\begin{center}
1.523 + \includegraphics[width=0.5cm]{flag-vymlink.png}
1.524 +\end{center}
1.525 +Clicking this flag in the toolbar or in the context menu of a branch
1.526 +will open the map in another tab (see \ref{tabs} for working with
1.527 +multiple maps). To delete an existing link, just press the "Cancel"
1.528 +button.
1.529 +
1.530 +Technical note: Internally \vym uses absolute paths, to avoid opening
1.531 +several tabs containing the same map. When a map is saved, this path is
1.532 +converted to a relative one (e.g. {\tt /home/user/vym.map} might become
1.533 +{\tt ./vym.map}. This makes it fairly easy to use multiple maps on
1.534 +different computers or export them to HTML in future.
1.535 +
1.536 +\subsection{Multiple maps} \label{tabs}
1.537 +You can work on multiple maps at the same time. Each new map is opened
1.538 +in another {\em tab}. The available tabs are shown just above the
1.539 +mapeditor. You can use the normal cut/copy/paste functions to
1.540 +copy data from one map to another.
1.541 +
1.542 +%todo
1.543 +
1.544 +%TODO
1.545 +%\subsubsection{Menus}
1.546 +%\subsubsection{Keyboard shortcuts}
1.547 +
1.548 +% Settings
1.549 +% Images
1.550 +% Copy & Paste
1.551 +% Working with tabs (multiple maps)
1.552 +% Exporting
1.553 +% Scrolling
1.554 +
1.555 +\section{Noteeditor} \label {noteeditor}
1.556 +If you want to save more text in a branch e.g. a complete email, a
1.557 +cooking recipe, or the whole source code of a software project, you can
1.558 +use the noteeditor.
1.559 +\begin{center}
1.560 + \includegraphics[width=8cm]{noteeditor.png}
1.561 +\end{center}
1.562 +This editor displays text associated to a branch selected in the
1.563 +mapeditor. To visualize that there maybe is no text yet, the noteeditor
1.564 +shows different background colors depending on its state:
1.565 +
1.566 +\subsection{States}
1.567 +Before you can type or paste text into it, you have
1.568 +to select a branch in the mapeditor. Note that the background color
1.569 +of the noteeditor indicates its state:
1.570 +\begin{itemize}
1.571 + \item black: no branch selected
1.572 + \item grey: no text entered yet
1.573 + \item white: text is already available
1.574 +\end{itemize}
1.575 +To show you in the mapeditor itself that there is a note with more
1.576 +information for a particular branch, a little note flag will appear next
1.577 +to the heading of the branch. See the lower branch on the right side:
1.578 +\begin{center}
1.579 + \includegraphics[width=8cm]{branches-flags.png}
1.580 +\end{center}
1.581 +
1.582 +\subsection{Import and export notes}
1.583 +The note is always saved automatically within the \vym file itself.
1.584 +Nevertheless sometimes it is nice to import a note from an external file
1.585 +or write it. Use "File\ra~Import" and "File\ra~Export" to do so.
1.586 +
1.587 +\subsection{Edit and print note}
1.588 +Editing works like in any simple texteditor, including undo and redo
1.589 +functions. You can delete the complete note by clicking the
1.590 +trashcan. Only the note itself is printed by clicking the printer icon.
1.591 +
1.592 +When pasting into the editor using the X11 copy\&paste mechanism, the
1.593 +editor will create a paragraph for each new line. Usually this is not
1.594 +wanted, so there you can convert all paragraphs into linebreaks by using
1.595 +Edit~\ra~Remove~Paragraphs or \key{ALT-X}.
1.596 +
1.597 +\subsection{RichText: Colors, paragraphs and formatted text}
1.598 +\vym supports formatted text (QT Rich Text) in the noteeditor since
1.599 +version 1.4.7. Colors and text attributes (e.g. italic, bold) can be
1.600 +set with the buttons above the text. The text itself is divided in
1.601 +paragraphs. For each paragraph the format can be set (e.g. centered,
1.602 +right). A paragraph is ended when a \key{Return} is entered. If you just
1.603 +want to begin a new line, press \key{CTRL-Return}.
1.604 +
1.605 +\subsection{Fonts and how to quickly switch them}
1.606 +The noteeditor is ment to be used for simple notes, not really as full
1.607 +featured text editor. Because of many requests \vym supports now
1.608 +formatted text in the noteeditor\footnote{
1.609 + \vym uses the QRichtText format, which is basically a subset of the
1.610 + formatting provided in HTML.}
1.611 +Two default fonts are supported which can be set in the Settings menu.
1.612 +One is a fixed width font, the other has variable width. The fixed font
1.613 +is usually used for emails, source code etc.\ while the variable font is
1.614 +used for simple notes, where one doesn't need fixed character widths.
1.615 +Both fonts can easily switched using the following symbol from the
1.616 +toolbar:
1.617 +\begin{center}
1.618 + \includegraphics[width=0.5cm]{formatfixedfont.png}
1.619 +\end{center}
1.620 +In the Settings menu both fonts can be set and also which font should be
1.621 +used for default.
1.622 +
1.623 +Additionally to the default fonts any font installed on your system can
1.624 +be used. Please note, that the chosen font also will be used for HTML
1.625 +exports, so you should only use fonts which are available generally.
1.626 +
1.627 +\subsection{Find text}
1.628 +The noteeditor itself has no Find function, use Find in the mapeditor,
1.629 +which will also search all notes (see \ref{findwindow}).
1.630 +
1.631 +\subsection{Paste text into note editor}
1.632 +Often you will paste text into the editor from another application e.g.
1.633 +an email. Normally \vym will generate a new paragraph for each new line.
1.634 +This usually is not what you want, so you can choose from the menu
1.635 +
1.636 +\subsection{Advanced actions}
1.637 +\subsubsection*{Edit \ra Convert subsubsections:}
1.638 +This turns subsubsections in selected text (or all text, if nothing is
1.639 +selected) into linebreaks. This is especially useful for snippets of
1.640 +source code.
1.641 +
1.642 +\subsubsection*{Edit \ra Join Lines:}
1.643 +Tries to format text, so that empty lines are used to delimit
1.644 +paragraphs. This is done for selected text (or all text, if nothing is
1.645 +selected). Especially useful for text like emails, meeting minutes etc.
1.646 +
1.647 +\section{Hello world}
1.648 +This section is about how \vym can interact with other applications.
1.649 +Many applications meanwhile can read and write their data using XML, the
1.650 +eXtensible Markup Language. \vym also uses XML to save its maps, see
1.651 +\ref{fileformat} for a more detailed description.
1.652 +
1.653 +So if your an application understands XML, chances are good that someone
1.654 +could write import/export filters for \vym. Volunteers are always
1.655 +welcome ;-)
1.656 +
1.657 +\subsection{Import} \label{import}
1.658 +
1.659 +\subsubsection*{KDE Bookmarks}
1.660 +The integrated bookmark editor in KDE is somewhat limited, so why not
1.661 +use \vym to maintain the bookmark mess? To create a new map containing
1.662 +your current KDE bookmarks just choose
1.663 +\begin{itemize}
1.664 + \item File \ra Import\ra KDE Bookmarks
1.665 +\end{itemize}
1.666 +
1.667 +\subsubsection*{Mind Manager}
1.668 +\vym has currently a very basic import filter to convert maps created by
1.669 +{\em Mind Manager}\footnote{Mind Manager is a professional software by
1.670 +Mindjet. Both names are registered trademarks by Mindjet. For more
1.671 +information see their website at
1.672 +\href{http://mindjet.de}{http://mindjet.de}} into \vym maps. Notes and
1.673 +pictures are not converted at the moment. You can import files with
1.674 +\begin{itemize}
1.675 + \item File \ra Import\ra Mind Manager
1.676 +\end{itemize}
1.677 +
1.678 +
1.679 +\subsubsection*{Directory structure}
1.680 +\vym can read a directory structure. This is mainly for
1.681 +testing \vym e.g. to easily create huge maps used for benchmarks (yes,
1.682 +there is still room to optimize \vym ;-)
1.683 +
1.684 +
1.685 +
1.686 +
1.687 +\subsection{Export} \label{export}
1.688 +\label{hideexport}
1.689 +Often you don't want to export the whole map, but just parts of it. For
1.690 +example you may have additional info you want to talk about in a
1.691 +presentation, while those parts should not be visible to the audience.
1.692 +To achieve this you can "hide" parts of the map during exports by
1.693 +setting the "hide in export" flag.
1.694 +\begin{center}
1.695 + \includegraphics[width=0.5cm]{flag-hideexport.png}
1.696 +\end{center}
1.697 +You can toggle this flag in the toolbar or by pressing \key{H}.
1.698 +Note that there is a global option in the settings menu to toggle the
1.699 +use of this flag. By default the flag is enabled.
1.700 +
1.701 +\subsubsection*{Open Office}
1.702 +Open Office beginning with version~2 uses the so called "Open Office
1.703 +Document Format", which can be written by \vym. The options are
1.704 +currently limited, but it possible to export presentations which can be
1.705 +opened in Open Office Impress. By selecting
1.706 +\begin{itemize}
1.707 + \item File \ra Export\ra Open Office
1.708 +\end{itemize}
1.709 +you get a file dialogue where you can choose the output file and the
1.710 +file type:
1.711 +\begin{center}
1.712 + \includegraphics[width=12cm]{export-oo.png}
1.713 +\end{center}
1.714 +The file types represent various templates, which can be created with
1.715 +some manual work from an existing Open Office document. The structure of
1.716 +\vym map is then inserted into a template.
1.717 +There are some limitations at the moment:
1.718 +\begin{itemize}
1.719 + \item \vym can't take care of page lengths, so you have to check and
1.720 + probably reedit in Open Office to avoid text running over the end of
1.721 + a page
1.722 + \item Images and flags are not used at the moment
1.723 + \item Notes are just written as plain text, without RichText
1.724 +\end{itemize}
1.725 +Some of the templates make use of {\em sections} e.g. insert the
1.726 +headings of mainbranches as chapters for sections into the presentation.
1.727 +
1.728 +\subsubsection*{Image}
1.729 +\vym supports all image formats which are natively supported by the
1.730 +QT~toolkit:
1.731 +BMP, JPEG, PBM, PGM, PNG, PPN, XPM, and XBM.
1.732 +For use in websites and for sending images by email PNG is a good
1.733 +recommodation regarding quality and size of the image. \vym uses QTs
1.734 +default options for compressing the images.
1.735 +
1.736 +\subsubsection*{ASCII}
1.737 +Exporting an image as text is somewhat experimental at the moment. Later
1.738 +this will probably done using stylesheets. So the output may change in
1.739 +future versions of \vym.
1.740 +
1.741 +\subsubsection*{\LaTeX}
1.742 +\vym can generate an input file for \LaTeX. Currently this is considered
1.743 +as experimental, there are no options (yet).
1.744 +By selecting
1.745 +\begin{itemize}
1.746 + \item File \ra Export\ra \LaTeX
1.747 +\end{itemize}
1.748 +you will be asked in a file dialog for the name of the output file. This
1.749 +file should be included in a \LaTeX document using command
1.750 +\begin{verbatim}
1.751 + \include{inputfile.tex}
1.752 +\end{verbatim}
1.753 +
1.754 +\subsubsection*{KDE Bookmarks}
1.755 +\vym will overwrite the KDE bookmarks file and then try to notify
1.756 +running konquerors via DCOP of the changed file. \vym does not create a
1.757 +backup!
1.758 +\begin{itemize}
1.759 + \item File \ra Export \ra KDE Bookmarks
1.760 +\end{itemize}
1.761 +
1.762 +
1.763 +\subsubsection*{XHTML (Webpages)}
1.764 +
1.765 +This is the format you want to use to create a webpage. For an example
1.766 +have a look at the \vym homepage:
1.767 +\href{http://www.InSilmaril.de/vym}{www.InSilmaril.de/vym}
1.768 +
1.769 +Some explanation how this works:
1.770 +Before a map is exported as XHTML, it will be first written as XML into a
1.771 +directory (see \ref{xmlexport}). Then the external program {\tt
1.772 +xsltproc}\footnote{On SUSE Linux {\tt xsltproc} is installed by
1.773 +default.}
1.774 +will be called to process the XML file and generate HTML code.
1.775 +A dialog allows to set various options:
1.776 +\begin{itemize}
1.777 + \item {\bf Include image:} If set, \vym will creat an image map at
1.778 + the top of the HTML output. Clicking on a branch in the map will
1.779 + jump to the corresponding section in the output.
1.780 +
1.781 + \item {\bf Colored headings:}
1.782 + If set to yes, \vym will color the headings in the text part with the
1.783 + same colors like in the map.
1.784 + \item {\bf Show Warnings:}
1.785 + If set to yes, \vym will ask before overwriting data.
1.786 + \item {\bf Show output:}
1.787 + This is useful mainly for debugging. It will show how the processing of
1.788 + the XML file works by calling the external {\tt xsltproc}.
1.789 +\end{itemize}
1.790 +Additionally the paths to the CSS and XSL stylesheets can be set. By
1.791 +default on SUSE~Linux they will be in {\tt /usr/share/vym/styles}.
1.792 +
1.793 +
1.794 +\subsubsection*{XML} \label{xmlexport}
1.795 +The map is written into a directory both as an image and as XML. The
1.796 +directory is set in a file dialog. If the directory is not empty, you
1.797 +will be questioned if you risk to overwrite its contents.
1.798 +
1.799 +It is possible to export different maps into the same directory. Each
1.800 +file generated will have the map's name as prefix, e.g. {\tt todo.vym}
1.801 +becomes {\tt todo.xml}, {\tt todo.png}, {\tt todo-image-1.png} and so
1.802 +on. This is useful if e.g. for a website several combined maps have to
1.803 +be stored in the same directory.
1.804 +
1.805 +\subsubsection*{Export a part of a map}
1.806 +Select a branch you want to export together with its childs, then open
1.807 +the context menu and choose {\em Save Selection}. This will create a
1.808 +file with the postfix {\tt .vyp}, which is an abbreviation for \lq vym
1.809 +part\rq.
1.810 +
1.811 +
1.812 +\section{Advanced Editing}
1.813 +
1.814 +\subsection{How to deal with Bookmarks} \label{bookmarks}
1.815 +\subsubsection*{Open new tabs instead of new windows}
1.816 +If you use konqueror as browser, \vym will remember the konqueror which
1.817 +was opened first by \vym. You can also press \key{Ctrl} and click to
1.818 +open the link in a new tab then.
1.819 +
1.820 +\vym can also open a new tab in Mozilla or Firefox using the remote
1.821 +command\footnote{\href{http://www.mozilla.org/unix/remote.html}{http://www.mozilla.org/unix/remote.html}}
1.822 +of these.
1.823 +
1.824 +\subsubsection*{Drag and Drop}
1.825 +If you want to keep bookmarks in a map, select a branch where you want
1.826 +to add the bookmark, then simply drag the URL from your browser to the
1.827 +map. Also you could use an existing heading as URL: Right click onto the
1.828 +branch and select "Use heading for URL".
1.829 +
1.830 +
1.831 +\subsubsection*{Directly access bookmark lists of a browser}
1.832 +Please see the sections \ref{import} and \ref{export} about
1.833 +Import and Export filters.
1.834 +
1.835 +\subsubsection*{Special URLs}
1.836 +\vym can turn an existing heading of a branch into an URL. Currently
1.837 +this works for Bugentries in the Novell Bugtracking system: Open the
1.838 +context menu of a branch (usually by right-clicking it) and select
1.839 +\begin{itemize}
1.840 + \item Create URL to Bugzilla
1.841 +\end{itemize}
1.842 +The URL will be build from the number in the heading.
1.843 +
1.844 +\subsection{Including images into a branch}
1.845 +The default setting of an image is to float "freely". They can be
1.846 +positioned everywhere, but they might end up in the same place as other
1.847 +parts of the map.
1.848 +
1.849 +The solution is to include them "into" a branch. This can be done via
1.850 +the context menu of their parent branch:
1.851 +\begin{itemize}
1.852 + \item Include images horizontally
1.853 + \item Include images vertically
1.854 +\end{itemize}
1.855 +The image ist still positioned relatively to its parent branch, but the
1.856 +heading and border of the branch adapt to the floating image, see below:
1.857 +\begin{center}
1.858 + \includegraphics[width=11cm]{includeImages.png}
1.859 +\end{center}
1.860 +
1.861 +\subsection{Modifier Modes}
1.862 +Modifiers are for example the \key{Shift}- or the \key{Alt}-keys. When
1.863 +pressed while doing actions with the mouse, they will cause \vym to use
1.864 +a "modified" action. E.g. you can move branches with mouse. If
1.865 +\key{Ctrl} or \key{Alt}is pressed while releasing the branch, it will be
1.866 +added above/below the target, not as child of the target.
1.867 +
1.868 +Without a modifier pressed, the first click on a branch just selects
1.869 +it. For the behaviour of the \key{Ctrl} modifier there are several
1.870 +options, which can be set from the modifier toolbar:
1.871 +\begin{center}
1.872 + \includegraphics[width=3cm]{modmodes.png}
1.873 +\end{center}
1.874 +The default is to copy the color from the clicked branch to the already
1.875 +selected branch. In the toolbar shown above the default modifier is
1.876 +selected, namely to copy the color of a branch. The second modifier
1.877 +let's you easily copy a whole branch with a single click. The third
1.878 +modifier lets you create {\em xLinks}, which will be explained in the
1.879 +next section.
1.880 +
1.881 +\subsection{Hide links of unselected objects}
1.882 +Sometimes it would be useful to position a branch freely, just like a
1.883 +mainbranch or an image. Though this is not possible (yet) for all
1.884 +branches, you can use a mainbranch and hide its connecting link to the
1.885 +mapcenter. This can be used e.g. for legends or a collection of vymLinks
1.886 +pointing to other maps:
1.887 +\begin{center}
1.888 + \includegraphics[width=9cm]{hiddenlink.png}
1.889 +\end{center}
1.890 +
1.891 +
1.892 +\subsection{XLinks} \label{xlinks}
1.893 +So far all the data in the \vym map has been treelike. Using xLinks you
1.894 +can link one branch to any other, just like attaching a rope between two
1.895 +branches in a real tree. This is especially useful in complex maps,
1.896 +where you want to have crossreferences which don't fit on the same
1.897 +visible area, which fits on your screen. The following example, which is
1.898 +part of the \vym package, still fits on one screen, but shows how data
1.899 +can be crosslinked. In the graphics there is a link from a task (prepare
1.900 +a presentation) to general information:
1.901 +\begin{center}
1.902 + \includegraphics[width=12cm]{xlink.png}
1.903 +\end{center}
1.904 +Note that a xLink which points to a branch that is not visible (because
1.905 +it is scrolled), is just show as a little horizontal arrow. In the
1.906 +screenshot above have a look at the \lq Tuesday\rq\ branch.
1.907 +
1.908 +\subsubsection*{Create a xLink}
1.909 +Choose the link mode from the modifier toolbar (by clicking or pressing
1.910 +\key{L}). Select the branch, where the xLink should start. Press the
1.911 +modifier key \key{Ctrl} and simultanously click on the branch where the
1.912 +link should end. (The link is already drawn before you release the mouse
1.913 +key). If you release the mouse over a branch the xLink becomes
1.914 +permanent.
1.915 +
1.916 +\subsubsection*{Modify or delete a xLink}
1.917 +Open the context menu of a branch and select \lq Edit xLink\rq. A
1.918 +submenu contains all the xLinks of the branch (if there are any). They
1.919 +are named like the branches, where they end. Choose one and
1.920 +the xLink dialogue opens, where you can set color, width and also delete
1.921 +the xLink.
1.922 +
1.923 +\subsubsection*{Follow a xLink}
1.924 +In a complext \vym map it sometimes comes handy to jump to the other end
1.925 +of a xLink. You can do this by opening the context menu of the branch
1.926 +and clicking on \lq Goto xLink\rq and selecting the xLink you want to
1.927 +follow.
1.928 +
1.929 +
1.930 +
1.931 +\subsection{Adding and removing branches}
1.932 +The context menu of a branch shows some more ways to add and delete data
1.933 +e.g. you can delete a branch while keeping its childs. The childs become
1.934 +linked to the parent of the previously removed branch.
1.935 +Similar branches can be inserted into existing maps. For keyboard
1.936 +shortcuts also have a look at the context menu.
1.937 +
1.938 +\subsection{Adding a whole map or a part of a map}
1.939 +Select a branch where you want to add a previously saved map ({\tt .vym})or a part
1.940 +of a map ({\tt .vyp}) , then open
1.941 +the context menu and choose {\em Add \ra Import}. For the import you can
1.942 +choose between {\em Import Add} and {\em Import Replace}: The imported
1.943 +data will be added after the selection resp. replace the selection.
1.944 +
1.945 +
1.946 +\section{\vym on Mac OS X}
1.947 +\subsection{Overview}
1.948 +Basically there are two ways to run \vym on Macs:
1.949 +\subsubsection*{QT Mac Edition:}
1.950 + \vym here provides the well known Mac look and feel. \vym is
1.951 + available as zipped Mac OS X application. It has been compiled and
1.952 + tested in Mac~OS~10.3, but should also work on Tiger. It is using
1.953 + the Mac version of Trolltechs QT library.
1.954 +\subsubsection*{X11}
1.955 + \vym can also be run using the Linux version, but then menus and
1.956 + handling will also be those of the Linux version e.g. The menu bar
1.957 + will look different.
1.958 +
1.959 +\subsection {Contextmenu and special keys}
1.960 +Most Macs unfortunatly just have a single mouse button. In order to show
1.961 +the context menu which usually would be opened with the right mouse
1.962 +button, you can click while pressing the \key{kommand}-key.
1.963 +
1.964 +Especially on Laptops some of the keys usually used on PC keyboards seem
1.965 +to be missing. The QT-Mac Edition of \vym has its own keyboard
1.966 +shortcuts. To find the shortcuts just have a look at all the menu
1.967 +entries, the shortcut is visible next to an entry. Toolbar buttons also
1.968 +may have shortcuts, just position the mouse pointer over a button and
1.969 +wait for the little help window to appear.
1.970 +
1.971 +\subsection {Viewing external links}
1.972 +\vym on Mac uses the system call {\tt /usr/bin/open} to view links.
1.973 +Mac~OS determines automatically if the link is a pdf or www page and
1.974 +opens the right browser.
1.975 +
1.976 +
1.977 +\begin{appendix}
1.978 +
1.979 +\section{Starting \vym}
1.980 +\subsection{Path to ressources}
1.981 +\vym will try to find its ressources (images, stylesheets, filters,
1.982 +etc.) in the following places:
1.983 +\begin{enumerate}
1.984 + \item Path given by the environment variable {\tt VYMHOME}.
1.985 + \item If called with the local option (see \ref{options} below),
1.986 + \vym will look for its data in the current directory.
1.987 + \item {\tt /usr/share/vym}
1.988 + \item {\tt /usr/local/share/vym}
1.989 +\end{enumerate}
1.990 +
1.991 +\subsection{Command line options} \label{options}
1.992 +\vym has the following options:
1.993 +\begin{center}
1.994 +\begin{tabular}{ccp{8cm}}\\
1.995 +\bf Option & \bf Comment & \bf Description \\ \hline
1.996 +v & version & Show version ov \vym\\
1.997 +l & local & Use local paths to stylesheets, translations, icons,
1.998 + etc. instead of system paths. Useful for testing\\
1.999 +h & help & Show help\\
1.1000 +q & quit & Quit immediatly after startup. Useful for benchmarks.\\
1.1001 +\end{tabular}
1.1002 +\end{center}
1.1003 +You can also give several filenames at the commandline to let \vym open
1.1004 +several maps at once.
1.1005 +
1.1006 +\section{Contributing to \vym}
1.1007 +So far I'd say I have written 98\% of the code on my own. No surprise,
1.1008 +that \vym exactly fits my own needs. Nevertheless I would like to
1.1009 +encourage all users of \vym to contribute. Maybe not only with feature
1.1010 +requests, but also with code, new import/export filters, translations
1.1011 +etc. In this appendix I'll try to show how easy it is to expand the
1.1012 +things you can do already with \vym. I really look forward to hear from
1.1013 +you!
1.1014 +
1.1015 +\subsection{Getting help}
1.1016 +
1.1017 +\subsubsection*{Frequently asked questions}
1.1018 +Please refer to the FAQ available on the \vym website:
1.1019 +\begin{center}
1.1020 +\href{http://www.InSilmaril.de/vym/faq.html}{http://www.InSilmaril.de/vym/faq.html}
1.1021 +\end{center}
1.1022 +
1.1023 +\subsubsection*{Mailinglists}
1.1024 +There are two mailinglists: {\tt vym-forum} is the \vym users forum to
1.1025 +discuss various questions, while {\tt vym-devel} is intended for people
1.1026 +interested in contributing to \vym. You can view the archives and
1.1027 +subscribe at
1.1028 +\begin{center}
1.1029 +\href{https://sourceforge.net/mail/?group_id=127802}{https://sourceforge.net/mail/?group\_id=127802}
1.1030 +\end{center}
1.1031 +
1.1032 +\subsubsection*{Contacting the author}\label{author}
1.1033 +Especially for support questions please try the mailinglists first. If
1.1034 +everything else fails you can contact the Uwe Drechsel at
1.1035 +\begin{center}
1.1036 +\href{mailto:vym@InSilmaril.de}{vym@InSilmaril.de}
1.1037 +\end{center}
1.1038 +
1.1039 +
1.1040 +
1.1041 +\subsection{How to report bugs}
1.1042 +Though Sourceforge has its own bugreporting system, I'd rather prefer if
1.1043 +you contact me directly (see \ref{author}) or even better: You can file
1.1044 +a bugreport in Bugzilla, the bugtracking system of openSUSE:
1.1045 +\begin{center}
1.1046 +\href{http://en.opensuse.org/Submit_a_bug}{http://en.opensuse.org/Submit\_a\_bug}
1.1047 +\end{center}
1.1048 +I build \vym regulary for openSUSE, so you may report it against a
1.1049 +recent version there, even if you use another Operating System.
1.1050 +Please don't forget to tell
1.1051 +\begin{itemize}
1.1052 + \item the exact steps needed to reproduce the bug
1.1053 + \item the version and build date of \vym (see the Help \ra About
1.1054 + \vym)
1.1055 + \item hardware and Operating System
1.1056 +\end{itemize}
1.1057 +
1.1058 +\subsection{Compiling from the sources}
1.1059 +\subsubsection{Getting the sources} \label{getsources}
1.1060 +You find the latest version of \vym at the project site:
1.1061 +\begin{center}
1.1062 +\href{https://sourceforge.net/projects/vym/}{https://sourceforge.net/projects/vym/}
1.1063 +\end{center}
1.1064 +There you can check them out of the source repository (CVS):\\
1.1065 +
1.1066 +\begin{verbatim}
1.1067 +cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/vym checkout code
1.1068 +\end{verbatim}
1.1069 +
1.1070 +\subsubsection{The Qt toolkit}
1.1071 +Qt is C++ toolkit for multiplatform GUI and application development. It
1.1072 +provides single-source portability across MS~Windows, Mac~OS~X, Linux
1.1073 +ans all major commercial Unix variants. Qt is also available for
1.1074 +embedded devices. Qt is a Trolltech product. For more information see
1.1075 +\begin{center}
1.1076 +\href{http://www.trolltech.com/qt/}{www.trolltech.com/qt}
1.1077 +\end{center}
1.1078 +
1.1079 +
1.1080 +\subsubsection{Compiling \vym }
1.1081 +Make sure you have installed your Qt environment properly, see the Qt
1.1082 +documentation for details. You need to have the Qt command {\tt qmake}
1.1083 +in your {\tt PATH}-environment, then run
1.1084 +\begin{verbatim}
1.1085 +qmake
1.1086 +make
1.1087 +make install
1.1088 +\end{verbatim}
1.1089 +The last command {\tt make install} needs root-permissions. Of course it
1.1090 +may be omitted, if you just want to test \vym.
1.1091 +
1.1092 +%\subsubsection*{Compiling \vym on Macs}
1.1093 +%TODO
1.1094 +
1.1095 +\subsection{\vym file format} \label{fileformat}
1.1096 +\vym maps usually have the postfix "{\tt .vym}" and represent a
1.1097 +compressed archive of data. If you want to have a
1.1098 +closer look into the data structure map called "mapname.vym",
1.1099 +just uncompress the map manually using
1.1100 +\begin{verbatim}
1.1101 + unzip mapname.vym
1.1102 +\end{verbatim}
1.1103 +This will create directories named {\tt images} and {\tt flags} in your
1.1104 +current directory and also the map itself, usually named {\tt
1.1105 +mapname.xml}.
1.1106 +The XML structure of \vym is pretty self explaining, just have a look at
1.1107 +{\tt mapname.xml}.
1.1108 +
1.1109 +This XML file can be loaded directly into \vym, it does not have to be
1.1110 +compressed. If you want to compress all the data yourself, use
1.1111 +\begin{verbatim}
1.1112 + zip -r mapname.vym .
1.1113 +\end{verbatim}
1.1114 +to compress all data in your current directory.
1.1115 +
1.1116 +\subsection{New features}
1.1117 +There are lots of features which might find their way into \vym.
1.1118 +Together with \vym you should have received a directory with several
1.1119 +maps e.g. on SUSE~LINUX this is
1.1120 +\begin{center}
1.1121 + {\tt /usr/share/doc/packages/vym/demos}
1.1122 +\end{center}
1.1123 +where you find the map {\tt todo.vym}. It lists quite a lot of things to
1.1124 +be done in future. If you have more ideas, contact the development team
1.1125 +at
1.1126 +{\tt vym-devel@lists.sourceforge.net}.
1.1127 +
1.1128 +
1.1129 +\subsection{New languages support}
1.1130 +In order to add a new language to \vym you need
1.1131 +the sources (see \ref{getsources}) and
1.1132 +an installation of Trolltechs QT. A part of QT are the development
1.1133 +tools, from those tools especially the translation tool "Linguist" is
1.1134 +needed.
1.1135 +
1.1136 +In some Linux distributions the development tools are in an extra package, e.g. on SUSE LINUX you should have installed:
1.1137 +\begin{verbatim}
1.1138 + qt3-devel.rpm
1.1139 + qt3-devel-doc.rpm
1.1140 + qt3-devel-tools.rpm
1.1141 + qt3-man.rpm
1.1142 +\end{verbatim}
1.1143 +If you don't have QT in your system, you can get it from
1.1144 + \href{http://www.trolltech.com}{http://www.trolltech.com} Once you
1.1145 + are able to compile vym yourself, you can translate the text in vym
1.1146 + itself by performing the following steps:
1.1147 +\begin{itemize}
1.1148 + \item Let's assume now your encoding is "NEW" instead of for example
1.1149 + "de" for german or "en" for english
1.1150 +
1.1151 + \item Copy the file {\tt lang/vym\_en.ts} to l{\tt ang/vym\_NEW.ts} (The code
1.1152 + itself contains the english version.)
1.1153 +
1.1154 + \item Add {\tt lang/vym\_NEW.ts} to the TRANSLATIONS section of vym.pro
1.1155 +
1.1156 + \item Run Linguist on {\tt vym\_NEW.ts} and do the translation
1.1157 +
1.1158 + \item Run {\tt lrelease} to create {\tt vym\_NEW.qm}
1.1159 +
1.1160 + \item Do a make install to install the new vym and check your translation
1.1161 +\end{itemize}
1.1162 +
1.1163 +If you feel brave, you can also translate the manual. It is written in
1.1164 +LaTeX, you just have to change the file tex/vym.tex. (Linguist and QT
1.1165 +are not needed, but it is useful to know how to work with LaTeX and esp.
1.1166 +pdflatex to create the PDF.)
1.1167 +
1.1168 +Please mail me every translation you have done. I can also give you a
1.1169 +developer access to the project, if you want to provide translations
1.1170 +regulary.
1.1171 +
1.1172 +\subsection{New export/import filters}
1.1173 +\vym supports various kinds of filters. Data can be written directly,
1.1174 +inserted into templates or it can be written as XML data and then
1.1175 +processed by XSL transformations.
1.1176 +
1.1177 +Most of the import/export functionality is available in the classes
1.1178 +ImportBase and ExportBase and subclasses. All of them can be found in
1.1179 +{\tt imports.h} and {\tt exports.h}.
1.1180 +
1.1181 +\subsubsection*{Direct import/export}
1.1182 +An example for a direct export is the XML export. This method touches
1.1183 +the implementation of nearly every object of \vym, so whenever possible
1.1184 +you should better use a XSL transformation instead.
1.1185 +
1.1186 +If you still want to know how it is done, start looking at
1.1187 +{\tt MapEditor::saveToDir} in {\tt mapeditor.cpp}.
1.1188 +
1.1189 +\subsubsection*{Templates}
1.1190 +Templates have been introduced to export to opendoc format used e.g. by
1.1191 +Open~Office. While I read the spec ($>$ 500 pages) about the format\footnote{
1.1192 +\href{http://www.oasis-open.org/}{http://www.oasis-open.org/}}\
1.1193 +I had the feeling that I did not want to write the export from scratch.
1.1194 +It would be too complex to adapt the styles to your own wishes, e.g. the
1.1195 +layout.
1.1196 +
1.1197 +Instead I analyzed existing Open~Office documents. I found out that
1.1198 +there are lots of redundant bits of information in a standard
1.1199 +presentation, for example each list item is contained in its own list.
1.1200 +In the end I came up with the default presentation style, which still
1.1201 +could be simplified, just in case you have free time\ldots
1.1202 +
1.1203 +The existing templates are still work in progress, before you spent too
1.1204 +much time developing your own style, please contact me. Basically the
1.1205 +following steps are needed to build your own style:
1.1206 +\begin{enumerate}
1.1207 + \item Create an example in Open Office. Use a title, authors name,
1.1208 + page heading etc.\ which you can easily grep for in the output file.
1.1209 +
1.1210 + \item Unzip the Open Office document into a directory.
1.1211 +
1.1212 + \item The main file is called {\tt content.xml}. All data is in one
1.1213 + single line. You can split the XML tags using the script {\tt
1.1214 + scripts/niceXML}, which is part of the \vym distribution.
1.1215 +
1.1216 + \item Copy the output of {\tt niceXML} to {\tt
1.1217 + content-template.xml}.
1.1218 +
1.1219 + \item Looking closer you will find lots of unused definitions, for
1.1220 + example of styles. You can delete or simply ignore them.
1.1221 +
1.1222 + \item Try to find your title, authors name. \vym will replace the
1.1223 + following strings while exporting:
1.1224 + \begin{center}
1.1225 + \begin{tabular}{lp{4cm}}
1.1226 + {\tt <!-- INSERT TITLE -->} & title of map \\
1.1227 + {\tt <!-- INSERT AUTHOR--> } & author \\
1.1228 + {\tt <!-- INSERT COMMENT -->} & comment \\
1.1229 + {\tt <!-- INSERT PAGES-->} & content of map \\
1.1230 + \end{tabular}
1.1231 + \end{center}
1.1232 + The content itself is generated in a similar way by inserting lists
1.1233 + into {\tt page-template}. Here the following substitutions are made:
1.1234 + \begin{center}
1.1235 + \begin{tabular}{lp{7cm}}
1.1236 + {\tt <!-- INSERT PAGE HEADING-->} & heading of a page
1.1237 + (mainbranch or child of mainbranch, depending on the use of
1.1238 + sections) \\
1.1239 + {\tt <!-- INSERT LIST --> } & all childs of the branch above \\
1.1240 + \end{tabular}
1.1241 + \end{center}
1.1242 +\end{enumerate}
1.1243 +Currently images are exported and notes just will appear as text
1.1244 +without formatting and colors.
1.1245 +
1.1246 +
1.1247 +
1.1248 +
1.1249 +\subsubsection*{XSL Transformation}
1.1250 +\vym uses XSL transformations while exporting (e.g. XHTML) and importing
1.1251 +data (e.g. KDE bookmarks). There is a little code needed to provide the
1.1252 +GUI, the rest is done using the {\tt .xsl} stylesheet and calling the
1.1253 +{\tt xsltproc} processor, which is part of libxslt, the XSLT
1.1254 +C library for GNOME.
1.1255 +
1.1256 +\end{appendix}
1.1257 +\end{document}
1.1258 +
1.1259 +%TODO
1.1260 +%\subsubsection{Menus}
1.1261 +%\subsubsection{Keyboard shortcuts}
1.1262 +%Where does vym save its settings? -> ~/.qt/vymrc
1.1263 +
1.1264 +
1.1265 +% INDEX
1.1266 +% mapeditor
1.1267 +% noteditor
1.1268 +% branch
1.1269 +% mapcenter
1.1270 +% heading
1.1271 +% flag
1.1272 +% orientation
1.1273 +% zoom
1.1274 +% orientation
1.1275 +% Toolbar
1.1276 +% Zoom
1.1277 +% Find
1.1278 +% statusbar
1.1279 +% link
1.1280 +% mainbranch
1.1281 +% subtree
1.1282 +% reorder
1.1283 +% scroll
1.1284 +% fold
1.1285 +% vymlink
1.1286 +% xlink
1.1287 +% modMode
1.1288 +% context menu
1.1289 +% Mac OS X
1.1290 +
1.1291 +
1.1292 +
1.1293 +\end{document}