More documentation, fixed small bug where links of unselected objects where visible again
1 \documentclass{article}
3 \usepackage[latin1]{inputenc}
13 \hypersetup{bookmarks, bookmarksopen,
14 pdftitle={VYM - a tool for visual thinking },
15 pdfauthor={Uwe Drechsel},
17 pdfkeywords={map, tool},
18 pdfpagemode={UseOutlines},
19 bookmarksopenlevel={1},
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]}
35 \includegraphics[width=8cm]{vym-logo-new.png}
37 VYM \\ -- \\View Your Mind}
38 \author{\textcopyright Uwe Drechsel }
49 \section{Introduction}
50 \subsection{What is a \vym map?}
51 A \vym map (in short words {\em map}) is a tree like structure:
53 \includegraphics[width=12cm]{example1.png}
55 Such maps can be drawn by hand on paper or a flip chart and help to
56 structure your thoughs. While a tree like structure like above can be
57 drawn by hand or any drawing software \vym offers
58 much more features to work with such maps. \vym is not another drawing
59 software, but a tool to store and modify information in an intuitive
60 way. For example you can reorder parts of the map by pressing a key or
61 add various information like a complete email by a simple mouse click.
63 \subsection{Why should I use maps? Time, Space and your Brain.}
64 \subsubsection*{Space}
65 A map can concentrate a very complex content on little space e.g. a
66 piece of paper. It helps to use both sides of your brain: the logical
67 side and also your creative side (e.g. by using pictures, colors and
68 keywords in a map, so called {\em anchors}). It is a technique to
69 organize the way you think: It can help you by developing, sorting and
70 memorizing your thoughts.
73 Because you just use keywords and drawings, it is much faster than good
74 old fashioned notes. Your brain memorizes things by associating them to
75 other things -- a map makes use of those connections and stimulates
79 \subsubsection*{Your Brain}
80 In 1960 the Prof. {\sc Roger Sperry} discovered that both hemispheres
81 of the human brain have different tasks (of course both of them
82 basically {\em can} do the same):
84 \begin{tabular}{|p{5.5cm}|p{5.5cm}|} \hline
85 Left side & Right side \\ \hline
87 \item verbal speech and writing
89 \item logical thinking
90 \item analyzing and details
97 \item visual thinking, day dreams
98 \item intuition and emotion
99 \item overview of things
101 \item art, music, dancing
102 \item non-linear thinking, connecting things
103 \item spatial awareness
104 \end{itemize} \\ \hline
107 In our science oriented society we have learned to mainly rely on our
108 left side of the brain, the "rational" one. In other cultures,
109 especially like the native americans and other "old" cultures, the right
110 side is much more important. Maps are just one way to stimulate the
111 other side and make use of additional ressources we all have.
114 \subsection{Where could I use a map?}
115 Here are some examples, how you can use those maps
117 \item to prepare articles, papers, books, talks, \ldots
118 \item to sort complex data
119 \item to memorize facts, persons, vocabulary, \ldots
120 \item to sort emails, files and bookmarks on your computer
121 \item to moderate conferences
124 \subsection{What you shouldn't do with a map...}
125 A map drawn by somebody shows the way the author thinks. There is
126 no right or wrong in the way it is drawn, so there is no way to criticize
127 it. "It is, what it is" ({\sc F.~Lehmann}).
132 \subsection{Internet Ressources}
133 A good starting point to learn more about maps in general is Wikipedia:
136 \href{http://en.wikipedia.org/wiki/Mind_map}{http://en.wikipedia.org/wiki/Mind\_map}
138 \href{http://de.wikipedia.org/wiki/Mindmap}{http://de.wikipedia.org/wiki/Mindmap}
144 \section{Concept of \vym}
145 %TODO may add a general introduction here...
146 \subsection{Windows: mapeditor and noteeditor}
147 \vym uses two windows: an editor for the map itself and another one for
148 notes, which are part of the map. Let's call them {\em mapeditor} and
151 \includegraphics[width=8cm]{windows.png}
153 Usually you will work in the {\em mapeditor} by just adding new
154 branches, moving around and reordering them. The various ways to do this
155 will be explained in \ref{mapeditor}. You can store additional
156 information e.g. the content of a email easily in a {\em branch}: Just
157 type or copy\&paste it into the {\em noteeditor}. Working with notes is
158 explained in \ref{noteeditor}
160 \subsection{Menus and Context menus}
161 On top of each window you find the menubar. The options you find there
162 are similar to those you are used from other applications. Note that
163 many (and even more) options are availabe via {\em context menus}. Those
164 are available if you right-click onto an object in a map (on Mac~OS~X
167 \subsection{Toolbars}
168 The toolbars in the mainwindows give quick access to many functions and
169 also visualize the state of an object. For example a part of of the map
170 can be hidden when the map is exported into an Open~Office presentation.
171 To show this the branch in the map will have a little cloud symbol,
172 which is also "switched on" in the toolbar.
174 Note that you can reposition all toolbars by simply grabbing them. For
175 example you can move the flags-toolbar from its original horizontal
176 position on top of the mapeditor to a vertical position on the right
177 side. You can even detach it and make it "float" separate from the other
178 windows. Or just insert it again at its original position.
181 The map itself has always a {\em mapcenter}. The
182 mapcenter has {\em branches} just like the trunk of a tree. Each branch
183 in turn may have branches again.
185 \includegraphics[width=10cm]{branches.png}
187 We will call a branch directly connected to the mapcenter a {\em
188 mainbranch}, because it determines the position of all its child
191 The mapcenter and the branches all have a {\em heading}. This is the
192 text you see in the mapeditor. Usually it should just be one or a few
193 words, so that one can easily keep track of the whole map.
196 In the toolbar above the mapeditor you see various symbols.
198 \includegraphics[width=8cm]{default-flags.png}
200 These are called {\em flags} and can be used to mark branches in the
201 map, e.g. if something is important or questionable.
202 There are also more flags set by \vym automatically to show additional
203 information, e.g. when a exists for a particular branch.
205 By default some of these flags are set exclusively e.g. when the
206 "thumb-up" flag is set, then the "thumb down" is unset and vice
207 versa. You can change this default behaviour in the settings menu.
209 %TODO add info about toolbars e.g. undo/redo, ...
211 \section{Mapeditor} \label {mapeditor}
212 \subsection{Start a new map}
213 After \vym is started two windows will open: the mapeditor and the
214 noteditor. Usually you will work in both windows, but at the moment we
215 will just need the mapeditor.
217 Select the mapcenter "New map" in the middle of the mapeditor by
218 left-clicking with the mouse. It will turn yellow to show that is
219 selected. There are several ways to add a new branch to the center:
221 \item Using the mouse: Open the context meny by clicking with the
222 right mouse button (CTRL-Click on Mac) onto the
223 mapcenter and choose Add \ra Add as child
224 \item Press \key{Ins} or \key{A}
226 A new branch will appear and you will be able to type the heading of the
227 branch. Finish adding the new branch by pressing \key{Enter}.
229 Sometimes it comes handy to add a new branch above or below the current
230 one. Use \key{Ins} together with \key{Shift} or \key{Ctrl}. It is also
231 possible to add a branch in such a way, that the current selection
232 becomes the child of the new branch, which is like inserting it {\em
233 before} the selection. This can be done using the context menu.
235 \subsection{Navigate through a map}
236 \subsubsection*{Select branches}
237 To select branches you can use the left button of your mouse or also the
238 arrow keys. Depending on the {\em orientation} of a branch type
239 \key{\la} or \key{\ra} to get nearer to the mapcenter or deeper
240 down into the branches. Within a set of branches, let's call them a
241 {\em subtree}, you can use \key{\ua} and \key{\da} to go up and down. You can
242 also use \key{Pos1} and \key{End} to select the first and last branch.
245 \subsubsection*{Zoom a map}
246 While adding more and more branches the size of the map may become
247 bigger than the mapeditor window. You can use the scrollbars on the
248 right and the bottom of your mapeditor window to scroll, but it is
249 easier to just scroll using the left mouse button: Click onto the {\em
250 canvas} itself, the empty space somewhere between the branches. The
251 mouse pointer will change from an arrow to a hand, now move the visible
252 part of the map to show the desired part.
254 If you select branches using the arrow keys, the map will scroll
255 to ensure that the selected branch is always visible.
257 Working with huge maps, the {\em zoom}-function comes in handy: You can
260 \item from the menu View \ra Zoom
261 \item the toolbar buttons
263 \includegraphics[width=3cm]{zoom-buttons.png}
266 The crossed magnifying lens resets the zoomed view to its original size.
269 \subsubsection*{Find Function} \label{findwindow}
270 With huge maps there is the need to have a
271 find function. Choose Edit \ra Find to open the Find Window:
273 \includegraphics[width=6cm]{find-window.png}
275 The text you enter here will be searched in all the headings and also in
276 notes. Everytime you press the "Find"-button it will look for the next
277 occurence, which then will be selected automatically. If the search
278 fails, there will appear a short message "Nothing found" or a few
279 seconds in the {\em statusbar} on the bottom of the mapeditor.
281 \subsubsection*{Keep the overview -- scroll a part of the map}
282 A very big subtree of a map e.g. a branch with hundreds of childs makes
283 it very hard to keep an overview over the whole map. You can hide all
284 the childs of a branch by {\em scrolling} it -- this function is also
285 often called {\em folding}. Think of the whole subtree as painted onto a
286 big newspaper. You can scroll the paper to a small roll, leaving just
287 the headline readable.
289 To scroll or unscroll a branch and its childs, press the
291 \item \key{Scroll} key or \key{S}
292 \item press the middle-mouse button or
293 \item choose the little scroll from the toolbar.
295 If you select parts of a scrolled branch e.g. using the find function or
296 by using the arrow-keys, it will unscroll temporary. This is shown as a
297 scroll with a little hour glass. If the temporary unscrolled part is not
298 longer needed, it will be hidden again automatically. It is also
299 possible to unscroll all branches using "Edit\ra Unscroll all scrolled
304 \subsection{Modify and move branches}
305 \subsubsection*{Modify the heading}
306 You can edit the heading by selecting the branch and then
308 \item pressing \key{Enter}
309 \item double-clicking with left mouse.
311 Just type the new heading (or edit the old one) and press \key{Enter}.
313 \subsubsection*{Move a branch}
314 The easiest way to move a branch is to select it with left-mouse and
315 drag it to the destination while keeping the mouse button pressed.
316 Depending on the branch it will be
318 \item moved to the destination or
319 \item {\em linked} to a new {\em parent} (mapcenter or branch)
321 If you drag the branch over another one or over the mapcenter, you will
322 notice that the link connecting it to the old parent will be changed to
323 lead to the new parent which is now under your mousepointer.
324 If you release the button now, the branch will be relinked.
326 If you release the button in the middle of nowhere, the result will
327 depend on the type of branch you are releasing:
329 \item A mainbranch is directly connected to the mapcenter.
330 It will stay on its new position.
331 \item An ordinary branch will "jump" back to its original position.
333 Thus you can easily rearrange the layout of the mainbranches to avoid
334 overlapping of their subtrees.
335 There is another convenient way to move branches, especially if you want
336 to {\em reorder} a subtree: You can move a branch up or down in a
339 \item pressing \key{\ua} and \key {\da}
340 \item selecting Edit \ra Move branch
341 \item clicking on the toolbar buttons:
343 \includegraphics[width=1.5cm]{move-buttons.png}
347 There is yet another way to move branches: If you press \key{Shift} or
348 \key{Ctrl} while moving with the mouse, the branch will be added above
349 or below the one the mouse pointer is over. This helps also to reorder a
352 \subsection{The right side of your brain - colors and images}
353 \subsubsection*{Change color of a heading}
354 You can also use colors to put more information into a map, e.g. use
355 red, green and more colors to prioritize tasks. Again you can
357 \item use the menu and choose e.g Format \rq Set Color
358 \item use the toolbar
360 \includegraphics[width=3cm]{color-buttons.png}
363 The first button (black in the graphic above) shows the actual color.
364 Clicking on it let's you choose another color. You can also "pick"
365 another color by selecting a branch with the desired color and using the
366 "pick color" button. Both of the buttons showing a bucket actually put
367 the current color to the selected branch. While the first one just
368 colors the heading of the selection, the last one also colors all the
369 childs of the selected branch.
372 A very useful function is the "copy color" using the mouse: Select the
373 branch which should get the new color, then press \key{Ctrl} and
374 simultanously click with left-mouse on another branch to copy its color
375 to the first one. Here the childs of the selection also will get the new
376 color, if you just want to color the selection itself, additionally
379 \subsubsection*{Use flags}
380 \vym provides various flags. You see them in the toolbar on top of the
381 mapeditor window. (Note: Like all toolbars you can also move them to the
382 left or the right side of the window or even detach them. Just grab the
383 very left "dotted" part of the toolbar with your left-mouse button.)
385 \includegraphics[width=8cm]{default-flags.png}
387 If you have a branch selected, you can set any number of flags by
388 clicking them in the toolbar. The toolbar buttons change their state and
389 always reflect the flags set in the selected branch.
391 Presently \vym uses two kinds of flags: {\em System Flags} and {\em
392 Standard Flags}. The standard flags are those shown in the toolbar.
393 System flags are set by \vym to indicate e.g. that there is additional
394 information in a note (more on this in \ref{noteeditor}). Later versions
395 of \vym may have another kind of flags, which may be edited by the user.
397 \subsubsection*{Images}
398 The easiest way to add an image to a branch is by dragging it e.g. from a
399 webbrowser to the mapeditor while a branch is selected there.
401 You can also add a image to a branch by opening the context menu of the
402 branch choose "Add Image". A
403 dialog window lets you choose the image to load.
404 \footnote{Supported image types are: PNG, BMP, XBM, XPM and PNM. It may
405 also support JPEG, MNG and GIF, if specially configured during
406 compilation (as done when \vym is part of SUSE LINUX).}
407 While an image is selected in the dialog, you can see a preview of the
408 image. It is also possible to select multiple images.
410 You can position the image anywhere you want, just drag it with left
411 mouse. To relink it to another branch, press \key{Shift} while moving
412 it. To delete it, press \key{Del}.
414 If you right-click onto an image, a context menu will open which let's
415 you first choose one of several image formats. Then a file dialog opens
416 to save the image. Hint: This is used to "export" the image, it will be
417 saved anyway in the map itself! You can also cut and
418 copy images, but it is not possible to add objects to an image\footnote{
419 Images are regarded as "extra feature". It would make working with
420 the map much more complex if e.g. images could be linked to images.}
422 The option \lq{\bf Use for export} \rq controls the output of exports
423 e.g. to HTML: If set to no, the image won't appear in the {\em text}
424 part of the output. This is useful for large images or if images are
425 used as a kind of frame e.g. the famous cloud symbol around a part of
426 the map. Those shouldn't appear in the middle of the text.
428 At the moment image support is preliminary: Images will be saved
429 together with all the other data of a map in the {\tt .vym}-file.
430 Later versions will include more functionality like resizing the images,
431 changing its z-value (put it into background) etc.
433 \subsubsection*{Frames}
434 A frame can be added to a branch by clicking with the
435 right-mouse button. A context menu will open, where you can choose the
436 frame. At the moment just a rectangle resp. "No Frame" will be offered,
437 nevertheless you can use images as frames. Have a look at the demo map
438 {\tt todo.vym} as an example, where the mapcenter is a cloud. You can
439 use an external drawing program like {\tt gimp} to create an image,
440 preferable with an transparency channel, so that you can design frames
441 which don't use a rectangular borderline, just like the cloud.
444 \subsection{Background design}
445 The design of the background of a map and also of the links connecting
446 various parts of the map can be changed by
448 \item Selecting Format from the menu
449 \item Right clicking onto the canvas, which will open a context menu
452 \subsubsection*{Background color}
453 The color is set (and also displayed) as "Set background color".
455 \subsubsection*{Link color}
456 Links connecting branches can be colored in one of the following ways:
458 \item use the color of the heading of the branch the links is
459 \item use {\em one} color for all links. The default color is blue.
462 The latter can be set with "Set link color". Check or uncheck the "Use
463 color of heading for link" option to choose one of the two designs for
466 \subsubsection*{Link style}
467 \vym offers four different styles for the appearences of links:
474 The "thick" styles only draw links starting at mapcenter thick, the rest
475 of the map is always painted "thin".
478 \subsection{Links to other documents and webpages}
479 \vym supports two kind of external links:
481 \item Document, which will be opened in an external webbrowser
482 \item \vym map, which will be opened in \vym itself
484 In addition to the external links there also internal ones, leading from one
485 branch in a map toanother one. Those are called {\em XLinks} and are explained
486 in section~\ref{xlinks}.
488 \subsubsection*{Webbrowser}
489 Modern Webbrowsers like {\tt konqueror} are able to display various
490 types of files, both local or in the internet. To enter the URL of
491 any document, right-click onto a branch or use the Edit Menu
492 and choose "Edit URL". Enter the path to your document (or copy and
493 paste it from your browser). Examples for valid paths are:
495 http://www.insilmaril.de/vym/index.html
496 file:/usr/share/doc/packages/vym/doc/vym.pdf
498 If an URL was entered, a little globe will appear in the branch. By
499 clicking on the globe in the toolbar or the context menu an external
501 The browser can be changed in the Settings Menu.}
504 \includegraphics[width=0.5cm]{flag-url.png}
506 If you want to keep bookmarks in a map, select a branch where you want
507 to add the bookmark, then simply drag the URL from your browser to the
508 map. Also you could use an existing heading as URL: Right click onto the
509 branch and select "Use heading for URL".
511 \subsubsection*{\vym map}
512 To link to to another map right click on a branch or choose "Edit \ra
513 Enter \vym link". A file dialog opens where you can choose the map. A
514 branch with a link is marked with
516 \includegraphics[width=0.5cm]{flag-vymlink.png}
518 Clicking this flag in the toolbar or in the context menu of a branch
519 will open the map in another tab (see \ref{tabs} for working with
520 multiple maps). To delete an existing link, just press the "Cancel"
523 Technical note: Internally \vym uses absolute paths, to avoid opening
524 several tabs containing the same map. When a map is saved, this path is
525 converted to a relative one (e.g. {\tt /home/user/vym.map} might become
526 {\tt ./vym.map}. This makes it fairly easy to use multiple maps on
527 different computers or export them to HTML in future.
529 \subsection{Multiple maps} \label{tabs}
530 You can work on multiple maps at the same time. Each new map is opened
531 in another {\em tab}. The available tabs are shown just above the
532 mapeditor. You can use the normal cut/copy/paste functions to
533 copy data from one map to another.
538 %\subsubsection{Menus}
539 %\subsubsection{Keyboard shortcuts}
544 % Working with tabs (multiple maps)
548 \section{Noteeditor} \label {noteeditor}
549 If you want to save more text in a branch e.g. a complete email, a
550 cooking recipe, or the whole source code of a software project, you can
553 \includegraphics[width=8cm]{noteeditor.png}
555 This editor displays text associated to a branch selected in the
556 mapeditor. To visualize that there maybe is no text yet, the noteeditor
557 shows different background colors depending on its state:
560 Before you can type or paste text into it, you have
561 to select a branch in the mapeditor. Note that the background color
562 of the noteeditor indicates its state:
564 \item black: no branch selected
565 \item grey: no text entered yet
566 \item white: text is already available
568 To show you in the mapeditor itself that there is a note with more
569 information for a particular branch, a little note flag will appear next
570 to the heading of the branch. See the lower branch on the right side:
572 \includegraphics[width=8cm]{branches-flags.png}
575 \subsection{Import and export notes}
576 The note is always saved automatically within the \vym file itself.
577 Nevertheless sometimes it is nice to import a note from an external file
578 or write it. Use "File\ra~Import" and "File\ra~Export" to do so.
580 \subsection{Edit and print note}
581 Editing works like in any simple texteditor, including undo and redo
582 functions. You can delete the complete note by clicking the
583 trashcan. Only the note itself is printed by clicking the printer icon.
585 When pasting into the editor using the X11 copy\&paste mechanism, the
586 editor will create a paragraph for each new line. Usually this is not
587 wanted, so there you can convert all paragraphs into linebreaks by using
588 Edit~\ra~Remove~Paragraphs or \key{ALT-X}.
590 \subsection{RichText: Colors, paragraphs and formatted text}
591 \vym supports formatted text (QT Rich Text) in the noteeditor since
592 version 1.4.7. Colors and text attributes (e.g. italic, bold) can be
593 set with the buttons above the text. The text itself is divided in
594 paragraphs. For each paragraph the format can be set (e.g. centered,
595 right). A paragraph is ended when a \key{Return} is entered. If you just
596 want to begin a new line, press \key{CTRL-Return}.
598 \subsection{Fonts and how to quickly switch them}
599 The noteeditor is ment to be used for simple notes, not really as full
600 featured text editor. Because of many requests \vym supports now
601 formatted text in the noteeditor\footnote{
602 \vym uses the QRichtText format, which is basically a subset of the
603 formatting provided in HTML.}
604 Two default fonts are supported which can be set in the Settings menu.
605 One is a fixed width font, the other has variable width. The fixed font
606 is usually used for emails, source code etc.\ while the variable font is
607 used for simple notes, where one doesn't need fixed character widths.
608 Both fonts can easily switched using the following symbol from the
611 \includegraphics[width=0.5cm]{formatfixedfont.png}
613 In the Settings menu both fonts can be set and also which font should be
616 Additionally to the default fonts any font installed on your system can
617 be used. Please note, that the chosen font also will be used for HTML
618 exports, so you should only use fonts which are available generally.
620 \subsection{Find text}
621 The noteeditor itself has no Find function, use Find in the mapeditor,
622 which will also search all notes (see \ref{findwindow}).
624 \subsection{Paste text into note editor}
625 Often you will paste text into the editor from another application e.g.
626 an email. Normally \vym will generate a new paragraph for each new line.
627 This usually is not what you want, so you can choose from the menu
629 \subsection{Advanced actions}
630 \subsubsection*{Edit \ra Convert subsubsections:}
631 This turns subsubsections in selected text (or all text, if nothing is
632 selected) into linebreaks. This is especially useful for snippets of
635 \subsubsection*{Edit \ra Join Lines:}
636 Tries to format text, so that empty lines are used to delimit
637 paragraphs. This is done for selected text (or all text, if nothing is
638 selected). Especially useful for text like emails, meeting minutes etc.
640 \section{Hello world}
641 This section is about how \vym can interact with other applications.
642 Many applications meanwhile can read and write their data using XML, the
643 eXtensible Markup Language. \vym also uses XML to save its maps, see
644 \ref{fileformat} for a more detailed description.
646 So if your an application understands XML, chances are good that someone
647 could write import/export filters for \vym. Volunteers are always
652 \subsubsection*{KDE Bookmarks}
653 The integrated bookmark editor in KDE is somewhat limited, so why not
654 use \vym to maintain the bookmark mess? To create a new map containing
655 your current KDE bookmarks just choose
657 \item File \ra Import\ra KDE Bookmarks
660 \subsubsection*{Mind Manager}
661 \vym has currently a very basic import filter to convert maps created by
662 {\em Mind Manager}\footnote{Mind Manager is a professional software by
663 Mindjet. Both names are registered trademarks by Mindjet. For more
664 information see their website at
665 \href{http://mindjet.de}{http://mindjet.de}} into \vym maps. Notes and
666 pictures are not converted at the moment. You can import files with
668 \item File \ra Import\ra Mind Manager
672 \subsubsection*{Directory structure}
673 \vym can read a directory structure. This is mainly for
674 testing \vym e.g. to easily create huge maps used for benchmarks (yes,
675 there is still room to optimize \vym ;-)
678 \vym supports various formats to help other applications.
680 \subsubsection*{Open Office}
681 Open Office beginning with version~2 uses the so called "Open Office
682 Document Format", which can be written by \vym. The options are
683 currently limited, but it possible to export presentations which can be
684 opened in Open Office Impress. By selecting
686 \item File \ra Export\ra Open Office
688 you get a file dialogue where you can choose the output file and the
691 \includegraphics[width=12cm]{export-oo.png}
693 The file types represent various templates, which can be created with
694 some manual work from an existing Open Office document. The structure of
695 \vym map is then inserted into a template.
696 There are some limitations at the moment:
698 \item \vym can't take care of page lengths, so you have to check and
699 probably reedit in Open Office to avoid text running over the end of
701 \item Images and flags are not used at the moment
702 \item Notes are just written as plain text, without RichText
704 Some of the templates make use of {\em sections} e.g. insert the
705 headings of mainbranches as chapters for sections into the presentation.
707 \subsubsection*{Image}
708 \vym supports all image formats which are natively supported by the
710 BMP, JPEG, PBM, PGM, PNG, PPN, XPM, and XBM.
711 For use in websites and for sending images by email PNG is a good
712 recommodation regarding quality and size of the image. \vym uses QTs
713 default options for compressing the images.
715 \subsubsection*{ASCII}
716 Exporting an image as text is somewhat experimental at the moment. Later
717 this will probably done using stylesheets. So the output may change in
718 future versions of \vym.
720 \subsubsection*{\LaTeX}
721 \vym can generate an input file for \LaTeX. Currently this is considered
722 as experimental, there are no options (yet).
725 \item File \ra Export\ra \LaTeX
727 you will be asked in a file dialog for the name of the output file. This
728 file should be included in a \LaTeX document using command
730 \include{inputfile.tex}
733 \subsubsection*{XHTML (Webpages)}
735 This is the format you want to use to create a webpage. For an example
736 have a look at the \vym homepage:
737 \href{http://www.InSilmaril.de/vym}{www.InSilmaril.de/vym}
739 Some explanation how this works:
740 Before a map is exported as XHTML, it will be first written as XML into a
741 directory (see \ref{xmlexport}). Then the external program {\tt
742 xsltproc}\footnote{On SUSE Linux {\tt xsltproc} is installed by
744 will be called to process the XML file and generate HTML code.
745 A dialog allows to set various options:
747 \item {\bf Include image:} If set, \vym will creat an image map at
748 the top of the HTML output. Clicking on a branch in the map will
749 jump to the corresponding section in the output.
751 \item {\bf Colored headings:}
752 If set to yes, \vym will color the headings in the text part with the
753 same colors like in the map.
754 \item {\bf Show Warnings:}
755 If set to yes, \vym will ask before overwriting data.
756 \item {\bf Show output:}
757 This is useful mainly for debugging. It will show how the processing of
758 the XML file works by calling the external {\tt xsltproc}.
760 Additionally the paths to the CSS and XSL stylesheets can be set. By
761 default on SUSE~Linux they will be in {\tt /usr/share/vym/styles}.
764 \subsubsection*{XML} \label{xmlexport}
765 The map is written into a directory both as an image and as XML. The
766 directory is set in a file dialog. If the directory is not empty, you
767 will be questioned if you risk to overwrite its contents.
769 It is possible to export different maps into the same directory. Each
770 file generated will have the map's name as prefix, e.g. {\tt todo.vym}
771 becomes {\tt todo.xml}, {\tt todo.png}, {\tt todo-image-1.png} and so
772 on. This is useful if e.g. for a website several combined maps have to
773 be stored in the same directory.
775 \subsubsection*{Export a part of a map}
776 Select a branch you want to export together with its childs, then open
777 the context menu and choose {\em Save Selection}. This will create a
778 file with the postfix {\tt .vyp}, which is an abbreviation for \lq vym
782 \section{Advanced Editing}
783 \vym offers a few shortcuts to let you work more quickly and literally
784 to connect any branches directly.
785 \subsection{Modifier Modes}
786 Modifiers are for example the \key{Shift}- or the \key{Alt}-keys. When
787 pressed while doing actions with the mouse, they will cause \vym to use
788 a "modified" action. E.g. you can move branches with mouse. If
789 \key{Ctrl} or \key{Alt}is pressed while releasing the branch, it will be
790 added above/below the target, not as child of the target.
792 Without a modifier pressed, the first click on a branch just selects
793 it. For the behaviour of the \key{Ctrl} modifier there are several
794 options, which can be set from the modifier toolbar:
796 \includegraphics[width=3cm]{modmodes.png}
798 The default is to copy the color from the clicked branch to the already
799 selected branch. In the toolbar shown above the default modifier is
800 selected, namely to copy the color of a branch. The second modifier
801 let's you easily copy a whole branch with a single click. The third
802 modifier lets you create {\em xLinks}, which will be explained in the
805 \subsection{XLinks} \label{xlinks}
806 So far all the data in the \vym map has been treelike. Using xLinks you
807 can link one branch to any other, just like attaching a rope between two
808 branches in a real tree. This is especially useful in complex maps,
809 where you want to have crossreferences which don't fit on the same
810 visible area, which fits on your screen. The following example, which is
811 part of the \vym package, still fits on one screen, but shows how data
812 can be crosslinked. In the graphics there is a link from a task (prepare
813 a presentation) to general information:
815 \includegraphics[width=12cm]{xlink.png}
817 Note that a xLink which points to a branch that is not visible (because
818 it is scrolled), is just show as a little horizontal arrow. In the
819 screenshot above have a look at the \lq Tuesday\rq\ branch.
821 \subsubsection*{Create a xLink}
822 Choose the link mode from the modifier toolbar (by clicking or pressing
823 \key{L}). Select the branch, where the xLink should start. Press the
824 modifier key \key{Ctr} and simultanously click on the branch where the
825 link should end. (The link is already drawn before you release the mouse
826 key). If you release the mouse over a branch the xLink becomes
829 \subsubsection*{Modify or delete a xLink}
830 Open the context menu of a branch and select \lq Edit xLink\rq. A
831 submenu contains all the xLinks of the branch (if there are any). They
832 are named like the branches, where they end. Choose one and
833 the xLink dialogue opens, where you can set color, width and also delete
836 \subsubsection*{Follow a xLink}
837 In a complext \vym map it sometimes comes handy to jump to the other end
838 of a xLink. You can do this by opening the context menu of the branch
839 and clicking on \lq Goto xLink\rq and selecting the xLink you want to
844 \subsection{Adding and removing branches}
845 The context menu of a branch shows some more ways to add and delete data
846 e.g. you can delete a branch while keeping its childs. The childs become
847 linked to the parent of the previously removed branch.
848 Similar branches can be inserted into existing maps. For keyboard
849 shortcuts also have a look at the context menu.
851 \subsection{Adding a whole map or a part of a map}
852 Select a branch where you want to add a previously saved map ({\tt .vym})or a part
853 of a map ({\tt .vyp}) , then open
854 the context menu and choose {\em Add \ra Import}. For the import you can
855 choose between {\em Import Add} and {\em Import Replace}: The imported
856 data will be added after the selection resp. replace the selection.
859 \section{\vym on Mac OS X}
860 \subsection{Overview}
861 Basically there are two ways to run \vym on Macs:
862 \subsubsection*{QT Mac Edition:}
863 \vym here provides the well known Mac look and feel. \vym is
864 available as zipped Mac OS X application. It has been compiled and
865 tested in Mac~OS~10.3, but should also work on Tiger. It is using
866 the Mac version of Trolltechs QT library.
868 \vym can also be run using the Linux version, but then menus and
869 handling will also be those of the Linux version e.g. The menu bar
872 \subsection {Contextmenu and special keys}
873 Most Macs unfortunatly just have a single mouse button. In order to show
874 the context menu which usually would be opened with the right mouse
875 button, you can click while pressing the \key{kommand}-key.
877 Especially on Laptops some of the keys usually used on PC keyboards seem
878 to be missing. The QT-Mac Edition of \vym has its own keyboard
879 shortcuts. To find the shortcuts just have a look at all the menu
880 entries, the shortcut is visible next to an entry. Toolbar buttons also
881 may have shortcuts, just position the mouse pointer over a button and
882 wait for the little help window to appear.
884 \subsection {Viewing external links}
885 \vym on Mac uses the system call {\tt /usr/bin/open} to view links.
886 Mac~OS determines automatically if the link is a pdf or www page and
887 opens the right browser.
892 \section{Contributing to \vym}
893 So far I'd say I have written 98\% of the code on my own. No surprise,
894 that \vym exactly fits my own needs. Nevertheless I would like to
895 encourage all users of \vym to contribute. Maybe not only with feature
896 requests, but also with code, new import/export filters, translations
897 etc. In this appendix I'll try to show how easy it is to expand the
898 things you can do already with \vym. I really look forward to hear from
901 \subsection{Getting help}
903 \subsubsection*{Frequently asked questions}
904 Please refer to the FAQ available on the \vym website:
906 \href{http://www.InSilmaril.de/vym/faq.html}{http://www.InSilmaril.de/vym/faq.html}
909 \subsubsection*{Mailinglists}
910 There are two mailinglists: {\tt vym-forum} is the \vym users forum to
911 discuss various questions, while {\tt vym-devel} is intended for people
912 interested in contributing to \vym. You can view the archives and
915 \href{https://sourceforge.net/mail/?group_id=127802}{https://sourceforge.net/mail/?group\_id=127802}
918 \subsubsection*{Contacting the author}
919 Especially for support questions please try the mailinglists first. If
920 everything else fails you can contact the Uwe Drechsel at
922 \href{mailto:vym@InSilmaril.de}{vym@InSilmaril.de}
926 \subsection{Compiling from the sources}
927 \subsubsection{Getting the sources} \label{getsources}
928 You find the latest version of \vym at the project site:
930 \href{https://sourceforge.net/projects/vym/}{https://sourceforge.net/projects/vym/}
932 There you can check them out of the source repository (CVS):\\
935 cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/vym checkout code
938 \subsubsection{The Qt toolkit}
939 Qt is C++ toolkit for multiplatform GUI and application development. It
940 provides single-source portability across MS~Windows, Mac~OS~X, Linux
941 ans all major commercial Unix variants. Qt is also available for
942 embedded devices. Qt is a Trolltech product. For more information see
944 \href{http://www.trolltech.com/qt/}{www.trolltech.com/qt}
948 \subsubsection{Compiling \vym }
949 Make sure you have installed your Qt environment properly, see the Qt
950 documentation for details. You need to have the Qt command {\tt qmake}
951 in your {\tt PATH}-environment, then run
957 The last command {\tt make install} needs root-permissions. Of course it
958 may be omitted, if you just want to test \vym.
960 %\subsubsection*{Compiling \vym on Macs}
963 \subsection{\vym file format} \label{fileformat}
964 \vym maps usually have the postfix "{\tt .vym}" and represent a
965 compressed archive of data. If you want to have a
966 closer look into the data structure map called "mapname.vym",
967 just uncompress the map manually using
971 This will create directories named {\tt images} and {\tt flags} in your
972 current directory and also the map itself, usually named {\tt
974 The XML structure of \vym is pretty self explaining, just have a look at
977 This XML file can be loaded directly into \vym, it does not have to be
978 compressed. If you want to compress all the data yourself, use
982 to compress all data in your current directory.
984 \subsection{New features}
985 There are lots of features which might find their way into \vym.
986 Together with \vym you should have received a directory with several
987 maps e.g. on SUSE~LINUX this is
989 {\tt /usr/share/doc/packages/vym/demos}
991 where you find the map {\tt todo.vym}. It lists quite a lot of things to
992 be done in future. If you have more ideas, contact the development team
994 {\tt vym-devel@lists.sourceforge.net}.
997 \subsection{New languages support}
998 In order to add a new language to \vym you need
999 the sources (see \ref{getsources}) and
1000 an installation of Trolltechs QT. A part of QT are the development
1001 tools, from those tools especially the translation tool "Linguist" is
1004 In some Linux distributions the development tools are in an extra package, e.g. on SUSE LINUX you should have installed:
1011 If you don't have QT in your system, you can get it from
1012 \href{http://www.trolltech.com}{http://www.trolltech.com} Once you
1013 are able to compile vym yourself, you can translate the text in vym
1014 itself by performing the following steps:
1016 \item Let's assume now your encoding is "NEW" instead of for example
1017 "de" for german or "en" for english
1019 \item Copy the file {\tt lang/vym\_en.ts} to l{\tt ang/vym\_NEW.ts} (The code
1020 itself contains the english version.)
1022 \item Add {\tt lang/vym\_NEW.ts} to the TRANSLATIONS section of vym.pro
1024 \item Run Linguist on {\tt vym\_NEW.ts} and do the translation
1026 \item Run {\tt lrelease} to create {\tt vym\_NEW.qm}
1028 \item Do a make install to install the new vym and check your translation
1031 If you feel brave, you can also translate the manual. It is written in
1032 LaTeX, you just have to change the file tex/vym.tex. (Linguist and QT
1033 are not needed, but it is useful to know how to work with LaTeX and esp.
1034 pdflatex to create the PDF.)
1036 Please mail me every translation you have done. I can also give you a
1037 developer access to the project, if you want to provide translations
1040 \subsection{New export/import filters}
1041 \vym supports various kinds of filters. Data can be written directly,
1042 inserted into templates or it can be written as XML data and then
1043 processed by XSL transformations.
1045 Most of the import/export functionality is available in the classes
1046 ImportBase and ExportBase and subclasses. All of them can be found in
1047 {\tt imports.h} and {\tt exports.h}.
1049 \subsubsection{Direct import/export}
1050 An example for a direct export is the XML export. This method touches
1051 the implementation of nearly every object of \vym, so whenever possible
1052 it should be tried to use for example a XSL transformation instead.
1054 If you still want to know how it is done, start looking at
1055 {\tt MapEditor::saveToDir} in {\tt mapeditor.cpp}.
1058 %\subsubsection{Templates}
1060 %\subsubsection{XSL Transformation}
1068 %\subsubsection{Menus}
1069 %\subsubsection{Keyboard shortcuts}
1070 %Where does vym save its settings? -> ~/.qt/vymrc