tex/vym.tex
 author insilmaril Wed, 11 Apr 2007 09:21:14 +0000 changeset 450 beb875135811 parent 420 b7447adddc9a child 479 7a651cb19690 permissions -rw-r--r--
     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 all branches using "Edit\ra Unscroll all scrolled

   309 branches".

   310

   311 You can also hide parts of the map while exporting it e.g. to a webpage

   312 or a presentation, see \ref{hideexport} for details.

   313

   314 \subsection{Modify and move branches}

   315 \subsubsection*{Modify the heading}

   316 You can edit the heading by selecting the branch and then

   317 \begin{itemize}

   318 	\item pressing \key{Enter}

   319 	\item double-clicking with left mouse.

   320 \end{itemize}

   321 Just type the new heading (or edit the old one) and press \key{Enter}.

   322

   323 \subsubsection*{Move a branch}

   324 The easiest way to move a branch is to select it with left-mouse and

   325 drag it to the destination while keeping the mouse button pressed.

   326 Depending on the branch  it will be

   327 \begin{itemize}

   328 	\item moved to the destination or

   329 	\item {\em linked} to a new {\em parent} (mapcenter or branch)

   330 \end{itemize}

   331 If you drag the branch over another one or over the mapcenter, you will

   332 notice that the  link connecting it to the old parent will be changed to

   333 lead to the  new parent which is now under your mousepointer.

   334 If you release the button now, the branch will be relinked.

   335

   336 If you release the button in the middle of nowhere, the result will

   337 depend on the type of branch you are releasing:

   338 \begin{itemize}

   339 	\item A mainbranch is directly connected to the mapcenter.

   340 		It will stay on its new position.

   341 	\item An ordinary branch will "jump" back to its original position.

   342 \end{itemize}

   343 Thus you can easily rearrange the layout of the mainbranches to avoid

   344 overlapping of their subtrees.

   345 There is another convenient way to move branches, especially if you want

   346 to {\em reorder} a subtree: You can move a branch up or down in a

   347 subtree by

   348 \begin{itemize}

   349 	\item pressing \key{\ua} and \key {\da}

   350 	\item selecting Edit \ra Move branch

   351 	\item clicking on the toolbar buttons:

   352 		\begin{center}

   353 			\includegraphics[width=1.5cm]{images/move-buttons.png}

   354 		\end{center}

   355 \end{itemize}

   356 %tipp

   357 There is yet another way to move branches: If you press \key{Shift} or

   358 \key{Ctrl} while moving with the mouse, the branch will be added above

   359 or below the one the mouse pointer is over. This helps also to reorder a

   360 map.

   361

   362 \subsection{The right side of your brain - colors and images}

   363 \subsubsection*{Change color of a heading}

   364 You can also use colors to put more information into a map, e.g. use

   365 red, green and more colors to prioritize tasks. Again you can

   366 \begin{itemize}

   367 	\item use the menu and choose e.g Format \rq Set Color

   368 	\item use the toolbar

   369 		\begin{center}

   370 			\includegraphics[width=3cm]{images/color-buttons.png}

   371 		\end{center}

   372 \end{itemize}

   373 The first button (black in the graphic above) shows the actual color.

   374 Clicking on it let's you choose another color. You can also "pick"

   375 another color by selecting a branch with the desired color and using the

   376 "pick color" button. Both of the buttons showing a bucket actually put

   377 the current color to the selected branch. While the first one just

   378 colors the heading of the selection, the last one also colors all the

   379 childs of the selected branch.

   380

   381 %tipp

   382 A very useful function is the "copy color" using the mouse: Select the

   383 branch which should get the new color, then press \key{Ctrl} and

   384 simultanously click with left-mouse on another branch to copy its color

   385 to the first one. Here the childs of the selection also will get the new

   386 color, if you just want to color the selection itself, additionally

   387 press \key{Shift}.

   388

   389 \subsubsection*{Use flags}

   390 \vym provides various flags. You see them in the toolbar on top of the

   391 mapeditor window. (Note: Like all toolbars you can also move them to the

   392 left or the right side of the window or even detach them. Just grab the

   393 very left "dotted" part of the toolbar with your left-mouse button.)

   394 \begin{center}

   395 	\includegraphics[width=8cm]{images/default-flags.png}

   396 \end{center}

   397 If you have a branch selected, you can set any number of flags by

   398 clicking them in the toolbar. The toolbar buttons change their state and

   399 always reflect the flags set in the selected branch.

   400

   401 Presently \vym uses two kinds of flags: {\em System Flags} and {\em

   402 Standard Flags}. The standard flags are those shown in the toolbar.

   403 System flags are set by \vym to indicate e.g. that there is additional

   404 information in a note (more on this in \ref{noteeditor}). Later versions

   405 of \vym may have another kind of flags, which may be edited by the user.

   406

   407 \subsubsection*{Images}

   408 The easiest way to add an image to a branch is by dragging it e.g. from a

   409 webbrowser to the mapeditor while a branch is selected there.

   410

   411 You can also add a image to a branch by opening the context menu of the

   412 branch choose "Add Image". A

   413 dialog window lets you choose the image to load.

   414 \footnote{Supported image types are: PNG, BMP, XBM, XPM and PNM. It may

   415 	also support JPEG, MNG and GIF, if specially configured during

   416 	compilation (as done when \vym is part of SUSE LINUX).}

   417 While an image is selected in the dialog, you can see a preview of the

   418 image. It is also possible to select multiple images.

   419

   420 You can position the image anywhere you want, just drag it with left

   421 mouse. To relink it to another branch, press \key{Shift} while moving

   422 it. To delete it, press \key{Del}.

   423

   424 If you right-click onto an image, a context menu will open which let's

   425 you first choose one of several image formats. Then a file dialog opens

   426 to save the image. Hint: This is used to "export" the image, it will be

   427 saved anyway in the map itself! You can also cut and

   428 copy images, but it is not possible to add objects to an image\footnote{

   429 	Images are regarded as "extra feature". It would make working with

   430 	the map much more complex if e.g. images could be linked to images.}

   431

   432 The option \lq{\bf Use for export} \rq controls the output of exports

   433 e.g. to HTML: If set to no, the image won't appear in the {\em text}

   434 part of the output. This is useful for large images or if images are

   435 used as a kind of frame e.g. the famous cloud symbol around a part of

   436 the map. Those shouldn't appear in the middle of the text.

   437

   438 At the moment image support is preliminary: Images will be saved

   439 together with all the other data of a map in the {\tt .vym}-file.

   440 Later versions will include more functionality like resizing the images,

   441 changing its z-value (put it into background) etc.

   442

   443 \subsubsection*{Frames}

   444 A frame can be added to a branch by clicking with the

   445 right-mouse button.  A context menu will open, where you can choose the

   446 frame. At the moment just a rectangle resp. "No Frame" will be offered,

   447 nevertheless you can use images as frames. Have a look at the demo map

   448 {\tt todo.vym} as an example, where the mapcenter is a cloud. You can

   449 use an external drawing program like {\tt gimp} to create an image,

   450 preferable with an transparency channel, so that you can design frames

   451 which don't use a rectangular borderline, just like the cloud.

   452

   453

   454 \subsection{Background design}

   455 The design of the background of a map and also of the links connecting

   456 various parts of the map can be changed by

   457 \begin{itemize}

   458 	\item Selecting Format from the menu

   459 	\item Right clicking onto the canvas, which will open a context menu

   460 \end{itemize}

   461

   462 \subsubsection*{Background color}

   463 The color is set (and also displayed) as "Set background color".

   464

   465 \subsubsection*{Link color}

   466 Links connecting branches can be colored in one of the following ways:

   467 \begin{itemize}

   468 	\item use the color of the heading of the branch the links is

   469 	\item use {\em one} color for all links. The default color is blue.

   470 	leading to.

   471 \end{itemize}

   472 The latter can be set with "Set link color". Check or uncheck the "Use

   473 color of heading for link" option to choose one of the two designs for

   474 your map.

   475

   476 \subsubsection*{Link style}

   477 \vym offers four different styles for the appearences of links:

   478 \begin{itemize}

   479 	\item Line

   480 	\item Parabel

   481 	\item Thick Line

   482 	\item Thick Parabel

   483 \end{itemize}

   484 The "thick" styles only draw links starting at mapcenter thick, the rest

   485 of the map is always painted "thin".

   486

   487

   488 \subsection{Links to other documents and webpages}

   489 \vym supports two kind of external links:

   490 \begin{itemize}

   491 	\item Document, which will be opened in an external webbrowser

   492 	\item \vym map, which will be opened in \vym itself

   493 \end{itemize}

   494 In addition to the external links there also internal ones, leading from one

   495 branch in a map toanother one. Those are called {\em XLinks} and are explained

   496 in section~\ref{xlinks}.

   497

   498 \subsubsection*{Webbrowser}

   499 Modern Webbrowsers like {\tt konqueror} are able to display various

   500 types of files, both local or in the internet. To enter the URL of

   501 any document, right-click  onto a branch or use the Edit Menu

   502 and choose "Edit URL". Enter the path to your document (or copy and

   503 paste it from your browser). Examples for valid paths are:

   504 \begin{verbatim}

   505 	http://www.insilmaril.de/vym/index.html

   506 	file:/usr/share/doc/packages/vym/doc/vym.pdf

   507 \end{verbatim}

   508 If an URL was entered, a little globe will appear in the branch. By

   509 clicking on the globe in the toolbar or the context menu an external

   510 browser\footnote{

   511 	The browser can be changed in the Settings Menu.}

   512 will be started.

   513 \begin{center}

   514 	\includegraphics[width=0.5cm]{images/flag-url.png}

   515 \end{center}

   516 For more information on working with bookmarks and webbrowsers see

   517 section \ref{bookmarks}.

   518

   519

   520 \subsubsection*{\vym map}

   521 To link to to another map right click on a branch or choose "Edit \ra

   522 Enter \vym link". A file dialog opens where you can choose the map. A

   523 branch with a link is marked with

   524 \begin{center}

   525 	\includegraphics[width=0.5cm]{images/flag-vymlink.png}

   526 \end{center}

   527 Clicking this flag in the toolbar or in the context menu of a branch

   528 will open the map in another tab (see \ref{tabs} for working with

   529 multiple maps). To delete an existing link, just press the "Cancel"

   530 button.

   531

   532 Technical note: Internally \vym uses absolute paths, to avoid opening

   533 several tabs containing the same map. When a map is saved, this path is

   534 converted to a relative one (e.g. {\tt /home/user/vym.map} might become

   535 {\tt ./vym.map}. This makes it fairly easy to use multiple maps on

   536 different computers or export them to HTML in future.

   537

   538 \subsection{Multiple maps} \label{tabs}

   539 You can work on multiple maps at the same time. Each new map is opened

   540 in another {\em tab}. The available tabs are shown just above the

   541 mapeditor. You can use the normal cut/copy/paste functions to

   542 copy data from one map to another.

   543

   544 %todo

   545

   546 %TODO

   547 %\subsubsection{Menus}

   548 %\subsubsection{Keyboard shortcuts}

   549

   550 % Settings

   551 % Images

   552 % Copy & Paste

   553 % Working with tabs (multiple maps)

   554 % Exporting

   555 % Scrolling

   556

   557 \section{Noteeditor} \label {noteeditor}

   558 If you want to save more text in a branch e.g. a complete email, a

   559 cooking recipe, or the whole source code of a software project, you can

   560 use the noteeditor.

   561 \begin{center}

   562 	\includegraphics[width=8cm]{images/noteeditor.png}

   563 \end{center}

   564 This editor displays text associated to a branch selected in the

   565 mapeditor. To visualize that there maybe is no text yet, the noteeditor

   566 shows different background colors depending on its state:

   567

   568 \subsection{States}

   569 Before you can type or paste text into it, you have

   570 to select a branch in the mapeditor. Note that the background color

   571 of the noteeditor indicates its state:

   572 \begin{itemize}

   573 	\item black: no branch selected

   574 	\item grey: no text entered yet

   575 	\item white: text is already available

   576 \end{itemize}

   577 To show you in the mapeditor itself that there is a note with more

   578 information for a particular branch, a little note flag will appear next

   579 to the heading of the branch. See the lower branch on the right side:

   580 \begin{center}

   581 	\includegraphics[width=8cm]{images/branches-flags.png}

   582 \end{center}

   583

   584 \subsection{Import and export notes}

   585 The note is always saved automatically within the \vym map itself.

   586 Nevertheless sometimes it is nice to import a note from an external file

   587 or write it. Use "Map\ra~Import" and "Map\ra~Export" to do so.

   588

   589 \subsection{Edit and print note}

   590 Editing works like in any simple texteditor, including undo and redo

   591 functions. You can delete the complete note by clicking the

   592 trashcan. Only the note itself is printed by clicking the printer icon.

   593

   594 When pasting into the editor using the X11 copy\&paste mechanism, the

   595 editor will create a paragraph for each new line. Usually this is not

   596 wanted, so there you can convert all paragraphs into linebreaks by using

   597 Edit~\ra~Remove~Paragraphs or \key{ALT-X}.

   598

   599 \subsection{RichText: Colors, paragraphs and formatted text}

   600 \vym supports formatted text (QT Rich Text) in the noteeditor since

   601 version 1.4.7.  Colors and text attributes (e.g. italic, bold) can be

   602 set with the buttons above the text.  The text itself is divided in

   603 paragraphs. For each paragraph the format can be set (e.g. centered,

   604 right). A paragraph is ended when a \key{Return} is entered. If you just

   605 want to begin a new line, press \key{CTRL-Return}.

   606

   607 \subsection{Fonts and how to quickly switch them}

   608 The noteeditor is ment to be used for simple notes, not really as full

   609 featured text editor. Because of many requests \vym supports now

   610 formatted text in the noteeditor\footnote{

   611 	\vym uses the QRichtText format, which is basically a subset of the

   612 	formatting provided in HTML.}

   613 Two default fonts are supported which can be set in the Settings menu.

   614 One is a fixed width font, the other has variable width. The fixed font

   615 is usually used for emails, source code etc.\ while the variable font is

   616 used for simple notes, where one doesn't need fixed character widths.

   617 Both fonts can easily switched using the following symbol from the

   618 toolbar:

   619 \begin{center}

   620 	\includegraphics[width=0.5cm]{images/formatfixedfont.png}

   621 \end{center}

   622 In the Settings menu both fonts can be set and also which font should be

   623 used for default.

   624

   625 Additionally to the default fonts any font installed on your system can

   626 be used. Please note, that the chosen font also will be used for HTML

   627 exports, so you should only use fonts which are available generally.

   628

   629 \subsection{Find text}

   630 The noteeditor itself has no Find function, use Find in the mapeditor,

   631 which will also search all notes (see \ref{findwindow}).

   632

   633 \subsection{Paste text into note editor}

   634 Often you will paste text into the editor from another application e.g.

   635 an email. Normally \vym will generate a new paragraph for each new line.

   636 This usually is not what you want, so you can choose from the menu

   637

   638 \section{Hello world}

   639 This section is about how \vym can interact with other applications.

   640 Many applications meanwhile can read and write their data using XML, the

   641 eXtensible Markup Language. \vym also uses XML to save its maps, see

   642 \ref{fileformat} for a more detailed description.

   643

   644 So if your an application understands XML, chances are good that someone

   645 could write import/export filters for \vym. Volunteers are always

   646 welcome ;-)

   647

   648 \subsection{Import} \label{import}

   649

   650 \subsubsection*{KDE Bookmarks}

   651 The integrated bookmark editor in KDE is somewhat limited, so why not

   652 use \vym to maintain the bookmark mess? To create a new map containing

   653 your current KDE bookmarks just choose

   654 \begin{itemize}

   655 	\item Map \ra Import\ra KDE Bookmarks

   656 \end{itemize}

   657

   658 \subsubsection*{Mind Manager}

   659 \vym has currently a very basic import filter to convert maps created by

   660 {\em Mind Manager}\footnote{Mind Manager is a professional software by

   661 Mindjet. Both names are registered trademarks by Mindjet. For more

   662 information see their website at

   663 \href{http://mindjet.de}{http://mindjet.de}} into \vym maps. Notes and

   664 pictures are not converted at the moment. You can import files with

   665 \begin{itemize}

   666 	\item Map \ra Import\ra Mind Manager

   667 \end{itemize}

   668

   669

   670 \subsubsection*{Directory structure}

   671 \vym can read a directory structure. This is mainly for

   672 testing \vym e.g. to easily create huge maps used for benchmarks (yes,

   673 there is still room to optimize \vym ;-)

   674

   675

   676

   677

   678 \subsection{Export}  \label{export}

   679 \label{hideexport}

   680 Often you don't want to export the whole map, but just parts of it. For

   681 example you may have additional info you want to talk about in a

   682 presentation, while those parts should not be visible to the audience.

   683 To achieve this you can "hide" parts of the map during exports by

   684 setting the "hide in export" flag.

   685 \begin{center}

   686 	\includegraphics[width=0.5cm]{images/flag-hideexport.png}

   687 \end{center}

   688 You can toggle this flag in the toolbar or by pressing \key{H}.

   689 Note that there is a global option in the settings menu to toggle the

   690 use of this flag. By default the flag is enabled.

   691

   692 \subsubsection*{Open Office}

   693 Open Office beginning with version~2 uses the so called "Open Office

   694 Document Format", which can be written by \vym. The options are

   695 currently limited, but it possible to export presentations which can be

   696 opened in Open Office Impress. By selecting

   697 \begin{itemize}

   698 	\item Map  \ra Export\ra Open Office

   699 \end{itemize}

   700 you get a file dialogue where you can choose the output file and the

   701 file type:

   702 \begin{center}

   703 	\includegraphics[width=12cm]{images/export-oo.png}

   704 \end{center}

   705 The file types represent various templates, which can be created with

   706 some manual work from an existing Open Office document. The structure of

   707 \vym map is then inserted into a template.

   708 There are some limitations at the moment:

   709 \begin{itemize}

   710 	\item \vym can't take care of page lengths, so you have to check and

   711 	probably reedit in Open Office to avoid text running over the end of

   712 	a page

   713 	\item Images and flags are not used at the moment

   714 	\item Notes are just written as plain text, without RichText

   715 \end{itemize}

   716 Some of the templates make use of {\em sections} e.g. insert the

   717 headings of mainbranches as chapters for sections into the presentation.

   718

   719 \subsubsection*{Image}

   720 \vym supports all image formats which are natively supported by the

   721 QT~toolkit:

   722 BMP, JPEG, PBM, PGM, PNG, PPN, XPM, and XBM.

   723 For use in websites and for sending images by email PNG is a good

   724 recommodation regarding quality and size of the image. \vym uses QTs

   725 default options for compressing the images.

   726

   727 \subsubsection*{ASCII}

   728 Exporting an image as text is somewhat experimental at the moment. Later

   729 this will probably done using stylesheets. So the output may change in

   730 future versions of \vym.

   731

   732 \subsubsection*{\LaTeX}

   733 \vym can generate an input file for \LaTeX. Currently this is considered

   734 as experimental, there are no options (yet).

   735 By selecting

   736 \begin{itemize}

   737 	\item Map  \ra Export\ra \LaTeX

   738 \end{itemize}

   739 you will be asked in a file dialog for the name of the output file. This

   740 file should be included in a \LaTeX document using command

   741 \begin{verbatim}

   742 	\include{inputfile.tex}

   743 \end{verbatim}

   744

   745 \subsubsection*{KDE Bookmarks}

   746 \vym will overwrite the KDE bookmarks file and then try to notify

   747 running konquerors via DCOP of the changed file. \vym does not create a

   748 backup!

   749 \begin{itemize}

   750 	\item Map \ra Export \ra KDE Bookmarks

   751 \end{itemize}

   752

   753

   754 \subsubsection*{XHTML (Webpages)}

   755

   756 This is the format you want to use to create a webpage. For an example

   757 have a look at the \vym homepage:

   758 \href{http://www.InSilmaril.de/vym}{www.InSilmaril.de/vym}

   759

   760 Some explanation how this works:

   761 Before a map is exported as XHTML, it will be first written as XML into a

   762 directory (see \ref{xmlexport}). Then the external program {\tt

   763 xsltproc}\footnote{On SUSE Linux {\tt xsltproc} is installed by

   764 default.}

   765 will be called to process the XML file and generate HTML code.

   766 A dialog allows to set various options:

   767 \begin{itemize}

   768 	\item {\bf Include image:} If set, \vym will creat an image map at

   769 	the top of the HTML output. Clicking on a branch in the map will

   770 	jump to the corresponding section in the output.

   771

   772 	\item {\bf Colored headings:}

   773 	If set to yes, \vym will color the headings in the text part  with the

   774 	same colors like in the map.

   775 	\item {\bf Show Warnings:}

   776 	If set to yes, \vym will ask before overwriting data.

   777 	\item {\bf Show output:}

   778 	This is useful mainly for debugging. It will show how the processing of

   779 	the XML file works by calling the external {\tt xsltproc}.

   780 \end{itemize}

   781 Additionally the paths to the CSS and XSL stylesheets can be set. By

   782 default on SUSE~Linux they will be in {\tt /usr/share/vym/styles}.

   783

   784

   785 \subsubsection*{XML} \label{xmlexport}

   786 The map is written into a directory both as an image and as XML. The

   787 directory is set in a file dialog. If the directory is not empty, you

   788 will be questioned if you risk to overwrite its contents.

   789

   790 It is possible to export different maps into the same directory. Each

   791 file generated will have the map's name as prefix, e.g. {\tt todo.vym}

   792 becomes {\tt todo.xml}, {\tt todo.png}, {\tt todo-image-1.png} and so

   793 on. This is useful if e.g. for a website several combined maps have to

   794 be stored in the same directory.

   795

   796 \subsubsection*{Export a part of a map}

   797 Select a branch you want to export together with its childs, then open

   798 the context menu and choose {\em Save Selection}. This will create a

   799 file with the postfix {\tt .vyp}, which is an abbreviation for \lq vym

   800 part\rq.

   801

   802

   803 \section{Advanced Editing}

   804

   805 \subsection{Changing the history: Undo and Redo}

   806 %FIXME

   807

   808 \subsection{Macros} \label{macros}

   809 Macros have been added to \vym in version~1.9.0. Each function key

   810 \key{F1} to \key{F12} holds a macro, which is executed on the current

   811 selection if the key is pressed. The default macros change the color of

   812 a subtree or set the frame of a branch:

   813 \begin{center}

   814 	\includegraphics[width=8cm]{images/macros.png}

   815 \end{center}

   816 Each macro is a \vym script, which is executed when the associated key

   817 is pressed. The default location of the scripts can be changed in the

   818 Settings menu. More information on using scripts in \vym is found in

   819 appendix~\ref{scripts}.

   820

   821 \subsection{How to deal with Bookmarks} \label{bookmarks}

   822 \subsubsection*{Open new tabs instead of new windows}

   823 If you use konqueror as browser, \vym will remember the konqueror which

   824 was opened first by \vym. You can also press \key{Ctrl} and click to

   825 open the link in a new tab then.

   826

   827 \vym can also open a new tab in Mozilla or Firefox using the remote

   828 command\footnote{\href{http://www.mozilla.org/unix/remote.html}{http://www.mozilla.org/unix/remote.html}}

   829 of these.

   830

   831 \subsubsection*{Drag and Drop}

   832 If you want to keep bookmarks in a map, select a branch where you want

   833 to add the bookmark, then simply drag the URL from your browser to the

   834 map. Also you could use an existing heading as URL: Right click onto the

   835 branch and select "Use heading for URL".

   836

   837

   838 \subsubsection*{Directly access bookmark lists of a browser}

   839 Please see the sections \ref{import} and \ref{export} about

   840 Import and Export filters.

   841

   842 \subsubsection*{Special URLs}

   843 \vym can turn an existing heading of a branch into an URL. Currently

   844 this works for Bugentries in the Novell Bugtracking system: Open the

   845 context menu of a branch (usually by right-clicking it) and select

   846 \begin{itemize}

   847 	\item Create URL to Bugzilla

   848 \end{itemize}

   849 The URL will be build from the number in the heading.

   850

   851 \subsection{Including images into a branch}

   852 The default setting of an image is to float "freely". They can be

   853 positioned everywhere, but they might end up in the same place as other

   854 parts of the map.

   855

   856 The solution is to include them "into" a branch. This can be done via

   857 the context menu of their parent branch:

   858 \begin{itemize}

   859 	\item Include images horizontally

   860 	\item Include images vertically

   861 \end{itemize}

   862 The image ist still positioned relatively to its parent branch, but the

   863 heading and border of the branch adapt to the floating image, see below:

   864 \begin{center}

   865 	\includegraphics[width=11cm]{images/includeImages.png}

   866 \end{center}

   867

   868 \subsection{Modifier Modes}

   869 Modifiers are for example the \key{Shift}- or the \key{Alt}-keys. When

   870 pressed while doing actions with the mouse, they will cause \vym to use

   871 a "modified" action. E.g. you can move branches with mouse. If

   872 \key{Ctrl} or \key{Alt}is pressed while releasing the branch, it will be

   873 added above/below the target, not as child of the target.

   874

   875 Without a modifier pressed, the first click on a branch just selects

   876 it. For the behaviour of the \key{Ctrl} modifier there are several

   877 options, which can be set from the modifier toolbar:

   878 \begin{center}

   879 	\includegraphics[width=3cm]{images/modmodes.png}

   880 \end{center}

   881 The default  is to copy the color from the clicked branch to the already

   882 selected branch. In the toolbar shown above the default modifier is

   883 selected, namely to copy the color of a branch. The second modifier

   884 let's you easily copy a whole branch with a single click. The third

   885 modifier lets you create {\em xLinks}, which will be explained in the

   886 next section.

   887

   888 \subsection{Hide links of unselected objects}

   889 Sometimes it would be useful to position a branch freely, just like a

   890 mainbranch or an image. Though this is not possible (yet) for all

   891 branches, you can use a mainbranch and hide its connecting link to the

   892 mapcenter. This can be used e.g. for legends or a collection of vymLinks

   893 pointing to other maps:

   894 \begin{center}

   895 	\includegraphics[width=9cm]{images/hiddenlink.png}

   896 \end{center}

   897 Change hiding of the links in the property window (opened in context

   898 menu or with \key{CTRL-I} on the "links"-tab.

   899

   900

   901 \subsection{XLinks} \label{xlinks}

   902 So far all the data in the \vym map has been treelike. Using xLinks you

   903 can link one branch to any other, just like attaching a rope between two

   904 branches in a real tree. This is especially useful in complex maps,

   905 where you want to have crossreferences which don't fit on the same

   906 visible area, which fits on your screen. The following example, which is

   907 part of the \vym package, still fits on one screen, but shows how data

   908 can be crosslinked. In the graphics there is a link from a task (prepare

   909 a presentation) to general information:

   910 \begin{center}

   911 	\includegraphics[width=12cm]{images/xlink.png}

   912 \end{center}

   913 Note that a xLink which points to a branch that is not visible (because

   914 it is scrolled), is just show as a little horizontal arrow. In the

   915 screenshot above have a look at the \lq Tuesday\rq\ branch.

   916

   917 \subsubsection*{Create a xLink}

   918 Choose the link mode from the modifier toolbar (by clicking or pressing

   919 \key{L}). Select the branch, where the xLink should start. Press the

   920 modifier key \key{Ctrl} and simultanously click on the branch where the

   921 link should end. (The link is already drawn before you release the mouse

   922 key). If you release the mouse over a branch the xLink becomes

   923 permanent.

   924

   925 \subsubsection*{Modify or delete a xLink}

   926 Open the context menu of a branch and select \lq Edit xLink\rq. A

   927 submenu contains all the xLinks of the branch (if there are any). They

   928 are named like the branches, where they end. Choose one and

   929 the xLink dialogue opens, where you can set color, width and also delete

   930 the xLink.

   931

   932 \subsubsection*{Follow a xLink}

   933 In a complext \vym map it sometimes comes handy to jump to the other end

   934 of a xLink. You can do this by opening the context menu of the branch

   935 and clicking on \lq Goto xLink\rq and selecting the xLink you want to

   936 follow.

   937

   938

   939

   940 \subsection{Adding and removing branches}

   941 The context menu of a branch shows some more ways to add and delete data

   942 e.g. you can delete a branch while keeping its childs. The childs become

   943 linked to the parent of the previously removed branch.

   944 Similar branches can be inserted into existing maps. For keyboard

   945 shortcuts also have a look at the context menu.

   946

   947 \subsection{Adding a whole map or a part of a map}

   948 Select a branch where you want to add a previously saved map ({\tt .vym})or a part

   949 of a map ({\tt .vyp}) , then open

   950 the context menu and choose {\em Add \ra Import}. For the import you can

   951 choose between {\em Import Add} and {\em Import Replace}: The imported

   952 data will be added after the selection resp. replace the selection.

   953

   954 \label{historywindow}

   955

   956 \section{\vym on Mac OS X}

   957 \subsection{Overview}

   958 Basically there are two ways to run \vym on Macs:

   959 \subsubsection*{QT Mac Edition:}

   960 	\vym here provides the well known Mac look and feel.  \vym is

   961 	available as zipped Mac OS X application. It has been compiled and

   962 	tested in Mac~OS~10.3, but should also work on Tiger. It is using

   963 	the Mac version of Trolltechs QT library.

   964 \subsubsection*{X11}

   965 	\vym can also be run using the Linux version, but then menus and

   966 	handling will also be those of the Linux version e.g. The menu bar

   967 	will look different.

   968

   969 \subsection	{Contextmenu and special keys}

   970 Most Macs unfortunatly just have a single mouse button. In order to show

   971 the context menu which usually would be opened with the right mouse

   972 button, you can click while pressing the \key{kommand}-key.

   973

   974 Especially on Laptops some of the keys usually used on PC keyboards seem

   975 to be missing. The QT-Mac Edition of \vym has its own keyboard

   976 shortcuts. To find the shortcuts just have a look at all the menu

   977 entries, the shortcut is visible next to an entry. Toolbar buttons also

   978 may have shortcuts, just position the mouse pointer over a button and

   979 wait for the little help window to appear.

   980

   981 \subsection {Viewing external links}

   982 \vym on Mac uses the system call {\tt /usr/bin/open} to view links.

   983 Mac~OS determines automatically if the link is a pdf or www page and

   984 opens the right browser.

   985

   986

   987 \begin{appendix}

   988

   989 \section{\vym initialization process and configuration}

   990 \subsection{Configuration file}

   991 On startup \vym will look for a configuration for user specific settings

   992 like window positions, toolbars etc. If this file does not already

   993 exist, it will be created. The file is located in the users home

   994 directory. The exact position depends on the platform:

   995 \begin{center}

   996 \begin{tabular}{cl}

   997 	{\bf Platform}	& {\bf Configuration file} \\ \hline

   998 	Linux		& {\tt $\sim$/.config/InSilmaril/vym.conf  } \\

   999 	Mac OS X	& {\tt /Users/NAME/Library/Preferences/com.insilmaril.vym.plist  } \\

  1000 \end{tabular}

  1001 \end{center}

  1002 The file can be edited manually, or on Mac~OS~X with Property List

  1003 Editor (installed with xtools).

  1004

  1005 \subsection{Path to ressources}

  1006 \vym will try to find its ressources (images, stylesheets, filters,

  1007 etc.) in the following places:

  1008 \begin{enumerate}

  1009 	\item Path given by the environment variable {\tt VYMHOME}.

  1010 	\item If called with the local option (see \ref{options} below),

  1011 	      \vym will look for its data in the current directory.

  1012 	\item {\tt /usr/share/vym}

  1013 	\item {\tt /usr/local/share/vym}

  1014 \end{enumerate}

  1015

  1016 \subsection{Command line options} \label{options}

  1017 \vym has the following options:

  1018 \begin{center}

  1019 \begin{tabular}{cccp{8cm}}\\

  1020 \bf Option	& \bf Comment & \bf Argument & \bf Description \\ \hline

  1021 v & version &			& Show version ov \vym\\

  1022 l & local	&			& Use local paths to stylesheets, translations, icons,

  1023                           etc. instead of system paths. Useful for testing\\

  1024 h & help	&			& Show help\\

  1025 r & run 	& filename	& Run script\\

  1026 q & quit	&			& Quit immediatly after startup. Useful for benchmarks.\\

  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}

  1034  %FIXME

  1035

  1036

  1037

  1038

  1039

  1040 \section{Contributing to \vym}

  1041 So far I'd say I have written 98\% of the code on my own. No surprise,

  1042 that \vym exactly fits my own needs. Nevertheless I would like to

  1043 encourage all users of  \vym to contribute. Maybe not only with feature

  1044 requests, but also with code, new import/export filters, translations

  1045 etc. In this appendix I'll try to show how easy it is to expand the

  1046 things you can do already with \vym. I really look forward to hear from

  1047 you!

  1048

  1049 \subsection{Getting help}

  1050

  1051 \subsubsection*{Frequently asked questions}

  1052 Please refer to the FAQ available on the \vym website:

  1053 \begin{center}

  1054 \href{http://www.InSilmaril.de/vym/faq.html}{http://www.InSilmaril.de/vym/faq.html}

  1055 \end{center}

  1056

  1057 \subsubsection*{Mailinglists}

  1058 There are two mailinglists: {\tt vym-forum} is the \vym users forum to

  1059 discuss various questions, while {\tt vym-devel} is intended for people

  1060 interested in contributing to \vym. You can view the archives and

  1061 subscribe at

  1062 \begin{center}

  1063 \href{https://sourceforge.net/mail/?group_id=127802}{https://sourceforge.net/mail/?group\_id=127802}

  1064 \end{center}

  1065

  1066 \subsubsection*{Contacting the author}\label{author}

  1067 Especially for support questions please try the mailinglists first. If

  1068 everything else fails you can contact the Uwe Drechsel at

  1069 \begin{center}

  1070 \href{mailto:vym@InSilmaril.de}{vym@InSilmaril.de}

  1071 \end{center}

  1072

  1073

  1074

  1075 \subsection{How to report bugs}

  1076 Though Sourceforge has its own bugreporting system, I'd rather prefer if

  1077 you contact me directly (see \ref{author}) or even better: You can file

  1078 a bugreport in Bugzilla, the bugtracking system of openSUSE:

  1079 \begin{center}

  1080 \href{http://en.opensuse.org/Submit_a_bug}{http://en.opensuse.org/Submit\_a\_bug}

  1081 \end{center}

  1082 I build \vym regulary for openSUSE, so you may report it against a

  1083 recent version there, even if you  use another Operating System.

  1084 Please don't forget to tell

  1085 \begin{itemize}

  1086 	\item the exact steps needed to reproduce the bug

  1087 	\item the version and build date of \vym (see the Help \ra About

  1088 	\vym)

  1089 	\item hardware and Operating System

  1090 \end{itemize}

  1091

  1092 \subsection{Compiling from the sources}

  1093 \subsubsection{Getting the sources} \label{getsources}

  1094 You find the latest version of \vym at the project site:

  1095 \begin{center}

  1096 \href{https://sourceforge.net/projects/vym/}{https://sourceforge.net/projects/vym/}

  1097 \end{center}

  1098 There you can check them out of the source repository (CVS):\\

  1099

  1100 \begin{verbatim}

  1101 cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/vym checkout code

  1102 \end{verbatim}

  1103

  1104 \subsubsection{The Qt toolkit}

  1105 Qt is C++ toolkit for multiplatform GUI and application development. It

  1106 provides single-source portability across MS~Windows, Mac~OS~X, Linux

  1107 ans all major commercial Unix variants. Qt is also available for

  1108 embedded devices. Qt is a Trolltech product. For more information see

  1109 \begin{center}

  1110 \href{http://www.trolltech.com/qt/}{www.trolltech.com/qt}

  1111 \end{center}

  1112

  1113

  1114 \subsubsection{Compiling \vym }

  1115 Make sure you have installed your Qt environment properly, see the Qt

  1116 documentation for details. You need to have the Qt command {\tt qmake}

  1117 in your {\tt PATH}-environment, then run

  1118 \begin{verbatim}

  1119 qmake

  1120 make

  1121 make install

  1122 \end{verbatim}

  1123 The last command {\tt make install} needs root-permissions. Of course it

  1124 may be omitted, if you just want to test \vym.

  1125

  1126 %\subsubsection*{Compiling \vym on Macs}

  1127 %FIXME

  1128

  1129 \subsection{\vym file format} \label{fileformat}

  1130 \vym maps usually have the postfix "{\tt .vym}" and represent a

  1131 compressed archive of data. If you want to have a

  1132 closer look into the data structure map called "mapname.vym",

  1133 just uncompress the map manually using

  1134 \begin{verbatim}

  1135 	unzip mapname.vym

  1136 \end{verbatim}

  1137 This will create directories named {\tt images} and {\tt flags} in your

  1138 current directory and also the map itself, usually named {\tt

  1139 mapname.xml}.

  1140 The XML structure of \vym is pretty self explaining, just have a look at

  1141 {\tt mapname.xml}.

  1142

  1143 This XML file can be loaded directly into \vym, it does not have to be

  1144 compressed. If you want to compress all the data yourself, use

  1145 \begin{verbatim}

  1146 	zip -r mapname.vym .

  1147 \end{verbatim}

  1148 to compress all data in your current directory.

  1149

  1150 \subsection{New features}

  1151 There are lots of features which might find their way into \vym.

  1152 Together with \vym you should have received a directory with several

  1153 maps e.g. on SUSE~LINUX this is

  1154 \begin{center}

  1155 	{\tt /usr/share/doc/packages/vym/demos}

  1156 \end{center}

  1157 where you find the map {\tt todo.vym}. It lists quite a lot of things to

  1158 be done in future. If you have more ideas, contact the development team

  1159 at

  1160 {\tt vym-devel@lists.sourceforge.net}.

  1161

  1162

  1163 \subsection{New languages support}

  1164 In order to add a new language to \vym you need

  1165 the sources (see \ref{getsources}) and

  1166 an installation of Trolltechs QT. A part of QT are the development

  1167 tools, from those tools especially the translation tool "Linguist" is

  1168 needed.

  1169

  1170 In some Linux distributions the development tools are in an extra package, e.g. on SUSE LINUX you should have installed:

  1171 \begin{verbatim}

  1172     qt3-devel.rpm

  1173     qt3-devel-doc.rpm

  1174     qt3-devel-tools.rpm

  1175     qt3-man.rpm

  1176 \end{verbatim}

  1177 If you don't have QT in your system, you can get it from

  1178 	\href{http://www.trolltech.com}{http://www.trolltech.com} Once you

  1179 	are able to compile vym yourself, you can translate the text in vym

  1180 	itself by performing the following steps:

  1181 \begin{itemize}

  1182 	\item Let's assume now your encoding is "NEW" instead of for example

  1183 	"de" for german or "en" for english

  1184

  1185 	\item Copy the file {\tt lang/vym\_en.ts} to l{\tt ang/vym\_NEW.ts} (The code

  1186 	itself contains the english version.)

  1187

  1188 	\item Add {\tt lang/vym\_NEW.ts} to the TRANSLATIONS section of vym.pro

  1189

  1190 	\item Run Linguist on {\tt vym\_NEW.ts} and do the translation

  1191

  1192 	\item Run {\tt lrelease} to create {\tt vym\_NEW.qm}

  1193

  1194 	\item Do a make install to install the new vym and check your translation

  1195 \end{itemize}

  1196

  1197 If you feel brave, you can also translate the manual. It is written in

  1198 LaTeX, you just have to change the file tex/vym.tex. (Linguist and QT

  1199 are not needed, but it is useful to know how to work with LaTeX and esp.

  1200 pdflatex to create the PDF.)

  1201

  1202 Please mail me every translation you have done. I can also give you a

  1203 developer access to the project, if you want to provide translations

  1204 regulary.

  1205

  1206 \subsection{New export/import filters}

  1207 \vym supports various kinds of filters. Data can be written directly,

  1208 inserted into templates or it can be written as XML data and then

  1209 processed by XSL transformations.

  1210

  1211 Most of the import/export functionality is available in the classes

  1212 ImportBase and ExportBase and subclasses. All of them can be found in

  1213 {\tt imports.h} and {\tt exports.h}.

  1214

  1215 \subsubsection*{Direct import/export}

  1216 An example for a direct export is the XML export. This method touches

  1217 the implementation of nearly every object of \vym, so whenever possible

  1218 you should better use a XSL transformation instead.

  1219

  1220 If you still want to know how it is done, start looking at

  1221 {\tt MapEditor::saveToDir} in {\tt mapeditor.cpp}.

  1222

  1223 \subsubsection*{Templates}

  1224 Templates have been introduced to export to opendoc format used e.g. by

  1225 Open~Office. While I read the spec ($>$ 500 pages) about the format\footnote{

  1226 \href{http://www.oasis-open.org/}{http://www.oasis-open.org/}}\

  1227 I had the feeling that I did not want to write the export from scratch.

  1228 It would be too complex to adapt the styles to your own wishes, e.g. the

  1229 layout.

  1230

  1231 Instead I analyzed existing Open~Office documents. I found out that

  1232 there are lots of redundant bits of information in a standard

  1233 presentation, for example each list item is contained in its own list.

  1234 In the end I came up with the default presentation style, which still

  1235 could be simplified, just in case you have free time\ldots

  1236

  1237 The existing templates are still work in progress, before you spent too

  1238 much time developing your own style, please contact me.  Basically the

  1239 following steps are needed to build your own style:

  1240 \begin{enumerate}

  1241 	\item Create an example in Open Office. Use a title, authors name,

  1242 	page heading etc.\ which you can easily grep for in the output file.

  1243

  1244 	\item Unzip  the Open Office document into a directory.

  1245

  1246 	\item The main file is called {\tt content.xml}. All data is in one

  1247 	single line. You can split the XML tags using the script {\tt

  1248 	scripts/niceXML}, which is part of the \vym distribution.

  1249

  1250 	\item Copy the output of {\tt niceXML} to {\tt

  1251 	content-template.xml}.

  1252

  1253 	\item Looking closer you will find lots of unused definitions, for

  1254 	example of styles. You can delete or simply ignore them.

  1255

  1256 	\item Try to find your title, authors name. \vym will replace the

  1257 	following strings while exporting:

  1258 	\begin{center}

  1259 	\begin{tabular}{lp{4cm}}

  1260 		{\tt <!-- INSERT TITLE -->}		& title of map \\

  1261 		{\tt <!-- INSERT AUTHOR-->	}	& author \\

  1262 		{\tt <!-- INSERT COMMENT -->}	& comment \\

  1263 		{\tt <!-- INSERT PAGES-->}		& content of map \\

  1264 	\end{tabular}

  1265 	\end{center}

  1266 	The content itself is generated in a similar way by inserting lists

  1267 	into {\tt page-template}. Here the following substitutions are made:

  1268 	\begin{center}

  1269 	\begin{tabular}{lp{7cm}}

  1270 		{\tt <!-- INSERT PAGE HEADING-->}		& heading of a page

  1271 		(mainbranch or child of mainbranch, depending on the use of

  1272 		sections) \\

  1273 		{\tt <!-- INSERT LIST -->	}	& all childs of the branch above \\

  1274 	\end{tabular}

  1275 	\end{center}

  1276 \end{enumerate}

  1277 Currently images are exported and notes just will appear as text

  1278 without formatting and colors.

  1279

  1280

  1281

  1282

  1283 \subsubsection*{XSL Transformation}

  1284 \vym uses XSL transformations while exporting (e.g. XHTML) and importing

  1285 data (e.g. KDE bookmarks). There is a little code needed to provide the

  1286 GUI, the rest is done using the {\tt .xsl} stylesheet and calling the

  1287 {\tt xsltproc} processor, which is part of libxslt, the XSLT

  1288 C  library  for  GNOME.

  1289

  1290 \end{appendix}

  1291 \end{document}

  1292

  1293 %TODO

  1294 %\subsubsection{Menus}

  1295 %\subsubsection{Keyboard shortcuts}

  1296 %Where does vym save its settings? -> ~/.qt/vymrc

  1297

  1298

  1299 % INDEX

  1300 % mapeditor

  1301 % noteditor

  1302 % branch

  1303 % mapcenter

  1304 % heading

  1305 % flag

  1306 % orientation

  1307 % zoom

  1308 % orientation

  1309 % Toolbar

  1310 % Zoom

  1311 % Find

  1312 % statusbar

  1313 % link

  1314 % mainbranch

  1315 % subtree

  1316 % reorder

  1317 % scroll

  1318 % fold

  1319 % vymlink

  1320 % xlink

  1321 % modMode

  1322 % context menu

  1323 % Mac OS X

  1324

  1325

  1326

  1327 \end{document}