Removed even more QT3 stuff. Drag & Drop not 100% functional at the moment
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\\ {\small Version 1.8.0}}
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 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.
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
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.
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
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):
88 \begin{tabular}{|p{5.5cm}|p{5.5cm}|} \hline
89 Left side & Right side \\ \hline
91 \item verbal speech and writing
93 \item logical thinking
94 \item analyzing and details
101 \item visual thinking, day dreams
102 \item intuition and emotion
103 \item overview of things
105 \item art, music, dancing
106 \item non-linear thinking, connecting things
107 \item spatial awareness
108 \end{itemize} \\ \hline
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.
118 \subsection{Where could I use a map?}
119 Here are some examples, how you can use those maps
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
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}).
136 \subsection{Internet Ressources}
137 A good starting point to learn more about maps in general is Wikipedia:
140 \href{http://en.wikipedia.org/wiki/Mind_map}{http://en.wikipedia.org/wiki/Mind\_map}
142 \href{http://de.wikipedia.org/wiki/Mindmap}{http://de.wikipedia.org/wiki/Mindmap}
148 \section{Concept of \vym}
149 %TODO may add a general introduction here...
150 \subsection{Windows: mapeditor and noteeditor}
151 \vym uses 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
155 \includegraphics[width=8cm]{windows.png}
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}
164 \subsection{Menus and Context menus}
165 On top of each window you find the menubar. The options you find there
166 are similar to those you are used from other applications. Note that
167 many (and even more) options are availabe via {\em context menus}. Those
168 are available if you right-click onto an object in a map (on Mac~OS~X
171 \subsection{Toolbars}
172 The toolbars in the mainwindows give quick access to many functions and
173 also visualize the state of an object. For example a part of of the map
174 can be hidden when the map is exported into an Open~Office presentation.
175 To show this the branch in the map will have a little cloud symbol,
176 which is also "switched on" in the toolbar.
178 Note that you can reposition all toolbars by simply grabbing them. For
179 example you can move the flags-toolbar from its original horizontal
180 position on top of the mapeditor to a vertical position on the right
181 side. You can even detach it and make it "float" separate from the other
182 windows. Or just insert it again at its original position.
185 The map itself has always a {\em mapcenter}. The
186 mapcenter has {\em branches} just like the trunk of a tree. Each branch
187 in turn may have branches again.
189 \includegraphics[width=10cm]{branches.png}
191 We will call a branch directly connected to the mapcenter a {\em
192 mainbranch}, because it determines the position of all its child
195 The mapcenter and the branches all have a {\em heading}. This is the
196 text you see in the mapeditor. Usually it should just be one or a few
197 words, so that one can easily keep track of the whole map.
200 In the toolbar above the mapeditor you see various symbols.
202 \includegraphics[width=8cm]{default-flags.png}
204 These are called {\em flags} and can be used to mark branches in the
205 map, e.g. if something is important or questionable.
206 There are also more flags set by \vym automatically to show additional
207 information, e.g. when a exists for a particular branch.
209 By default some of these flags are set exclusively e.g. when the
210 "thumb-up" flag is set, then the "thumb down" is unset and vice
211 versa. You can change this default behaviour in the settings menu.
213 %TODO add info about toolbars e.g. undo/redo, ...
215 \section{Mapeditor} \label {mapeditor}
216 \subsection{Start a new map}
217 After \vym is started two windows will open: the mapeditor and the
218 noteditor. Usually you will work in both windows, but at the moment we
219 will just need the mapeditor.
221 Select the mapcenter "New map" in the middle of the mapeditor by
222 left-clicking with the mouse. It will turn yellow to show that is
223 selected. There are several ways to add a new branch to the center:
225 \item Using the mouse: Open the context meny by clicking with the
226 right mouse button (CTRL-Click on Mac) onto the
227 mapcenter and choose Add \ra Add as child
228 \item Press \key{Ins} or \key{A}
230 A new branch will appear and you will be able to type the heading of the
231 branch. Finish adding the new branch by pressing \key{Enter}.
233 Sometimes it comes handy to add a new branch above or below the current
234 one. Use \key{Ins} together with \key{Shift} or \key{Ctrl}. It is also
235 possible to add a branch in such a way, that the current selection
236 becomes the child of the new branch, which is like inserting it {\em
237 before} the selection. This can be done using the context menu.
239 \subsection{Navigate through a map}
240 \subsubsection*{Select branches}
241 To select branches you can use the left button of your mouse or also the
242 arrow keys. Depending on the {\em orientation} of a branch type
243 \key{\la} or \key{\ra} to get nearer to the mapcenter or deeper
244 down into the branches. Within a set of branches, let's call them a
245 {\em subtree}, you can use \key{\ua} and \key{\da} to go up and down. You can
246 also use \key{Pos1} and \key{End} to select the first and last branch.
249 \subsubsection*{Zoom a map}
250 While adding more and more branches the size of the map may become
251 bigger than the mapeditor window. You can use the scrollbars on the
252 right and the bottom of your mapeditor window to scroll, but it is
253 easier to just scroll using the left mouse button: Click onto the {\em
254 canvas} itself, the empty space somewhere between the branches. The
255 mouse pointer will change from an arrow to a hand, now move the visible
256 part of the map to show the desired part.
258 If you select branches using the arrow keys, the map will scroll
259 to ensure that the selected branch is always visible.
261 Working with huge maps, the {\em zoom}-function comes in handy: You can
264 \item from the menu View \ra Zoom
265 \item the toolbar buttons
267 \includegraphics[width=3cm]{zoom-buttons.png}
270 The crossed magnifying lens resets the zoomed view to its original size.
273 \subsubsection*{Find Function} \label{findwindow}
274 With huge maps there is the need to have a
275 find function. Choose Edit \ra Find to open the Find Window:
277 \includegraphics[width=6cm]{find-window.png}
279 The text you enter here will be searched in all the headings and also in
280 notes. Everytime you press the "Find"-button it will look for the next
281 occurence, which then will be selected automatically. If the search
282 fails, there will appear a short message "Nothing found" or a few
283 seconds in the {\em statusbar} on the bottom of the mapeditor.
285 \subsubsection*{Keep the overview -- scroll a part of the map}
286 A very big subtree of a map e.g. a branch with hundreds of childs makes
287 it very hard to keep an overview over the whole map. You can hide all
288 the childs of a branch by {\em scrolling} it -- this function is also
289 often called {\em folding}. Think of the whole subtree as painted onto a
290 big newspaper. You can scroll the paper to a small roll, leaving just
291 the headline readable.
293 To scroll or unscroll a branch and its childs, press the
295 \item \key{Scroll} key or \key{S}
296 \item press the middle-mouse button or
297 \item choose the little scroll from the toolbar.
299 If you select parts of a scrolled branch e.g. using the find function or
300 by using the arrow-keys, it will unscroll temporary. This is shown as a
301 scroll with a little hour glass. If the temporary unscrolled part is not
302 longer needed, it will be hidden again automatically. It is also
303 possible to unscroll all branches using "Edit\ra Unscroll all scrolled
306 You can also hide parts of the map while exporting it e.g. to a webpage
307 or a presentation, see \ref{hideexport} for details.
309 \subsection{Modify and move branches}
310 \subsubsection*{Modify the heading}
311 You can edit the heading by selecting the branch and then
313 \item pressing \key{Enter}
314 \item double-clicking with left mouse.
316 Just type the new heading (or edit the old one) and press \key{Enter}.
318 \subsubsection*{Move a branch}
319 The easiest way to move a branch is to select it with left-mouse and
320 drag it to the destination while keeping the mouse button pressed.
321 Depending on the branch it will be
323 \item moved to the destination or
324 \item {\em linked} to a new {\em parent} (mapcenter or branch)
326 If you drag the branch over another one or over the mapcenter, you will
327 notice that the link connecting it to the old parent will be changed to
328 lead to the new parent which is now under your mousepointer.
329 If you release the button now, the branch will be relinked.
331 If you release the button in the middle of nowhere, the result will
332 depend on the type of branch you are releasing:
334 \item A mainbranch is directly connected to the mapcenter.
335 It will stay on its new position.
336 \item An ordinary branch will "jump" back to its original position.
338 Thus you can easily rearrange the layout of the mainbranches to avoid
339 overlapping of their subtrees.
340 There is another convenient way to move branches, especially if you want
341 to {\em reorder} a subtree: You can move a branch up or down in a
344 \item pressing \key{\ua} and \key {\da}
345 \item selecting Edit \ra Move branch
346 \item clicking on the toolbar buttons:
348 \includegraphics[width=1.5cm]{move-buttons.png}
352 There is yet another way to move branches: If you press \key{Shift} or
353 \key{Ctrl} while moving with the mouse, the branch will be added above
354 or below the one the mouse pointer is over. This helps also to reorder a
357 \subsection{The right side of your brain - colors and images}
358 \subsubsection*{Change color of a heading}
359 You can also use colors to put more information into a map, e.g. use
360 red, green and more colors to prioritize tasks. Again you can
362 \item use the menu and choose e.g Format \rq Set Color
363 \item use the toolbar
365 \includegraphics[width=3cm]{color-buttons.png}
368 The first button (black in the graphic above) shows the actual color.
369 Clicking on it let's you choose another color. You can also "pick"
370 another color by selecting a branch with the desired color and using the
371 "pick color" button. Both of the buttons showing a bucket actually put
372 the current color to the selected branch. While the first one just
373 colors the heading of the selection, the last one also colors all the
374 childs of the selected branch.
377 A very useful function is the "copy color" using the mouse: Select the
378 branch which should get the new color, then press \key{Ctrl} and
379 simultanously click with left-mouse on another branch to copy its color
380 to the first one. Here the childs of the selection also will get the new
381 color, if you just want to color the selection itself, additionally
384 \subsubsection*{Use flags}
385 \vym provides various flags. You see them in the toolbar on top of the
386 mapeditor window. (Note: Like all toolbars you can also move them to the
387 left or the right side of the window or even detach them. Just grab the
388 very left "dotted" part of the toolbar with your left-mouse button.)
390 \includegraphics[width=8cm]{default-flags.png}
392 If you have a branch selected, you can set any number of flags by
393 clicking them in the toolbar. The toolbar buttons change their state and
394 always reflect the flags set in the selected branch.
396 Presently \vym uses two kinds of flags: {\em System Flags} and {\em
397 Standard Flags}. The standard flags are those shown in the toolbar.
398 System flags are set by \vym to indicate e.g. that there is additional
399 information in a note (more on this in \ref{noteeditor}). Later versions
400 of \vym may have another kind of flags, which may be edited by the user.
402 \subsubsection*{Images}
403 The easiest way to add an image to a branch is by dragging it e.g. from a
404 webbrowser to the mapeditor while a branch is selected there.
406 You can also add a image to a branch by opening the context menu of the
407 branch choose "Add Image". A
408 dialog window lets you choose the image to load.
409 \footnote{Supported image types are: PNG, BMP, XBM, XPM and PNM. It may
410 also support JPEG, MNG and GIF, if specially configured during
411 compilation (as done when \vym is part of SUSE LINUX).}
412 While an image is selected in the dialog, you can see a preview of the
413 image. It is also possible to select multiple images.
415 You can position the image anywhere you want, just drag it with left
416 mouse. To relink it to another branch, press \key{Shift} while moving
417 it. To delete it, press \key{Del}.
419 If you right-click onto an image, a context menu will open which let's
420 you first choose one of several image formats. Then a file dialog opens
421 to save the image. Hint: This is used to "export" the image, it will be
422 saved anyway in the map itself! You can also cut and
423 copy images, but it is not possible to add objects to an image\footnote{
424 Images are regarded as "extra feature". It would make working with
425 the map much more complex if e.g. images could be linked to images.}
427 The option \lq{\bf Use for export} \rq controls the output of exports
428 e.g. to HTML: If set to no, the image won't appear in the {\em text}
429 part of the output. This is useful for large images or if images are
430 used as a kind of frame e.g. the famous cloud symbol around a part of
431 the map. Those shouldn't appear in the middle of the text.
433 At the moment image support is preliminary: Images will be saved
434 together with all the other data of a map in the {\tt .vym}-file.
435 Later versions will include more functionality like resizing the images,
436 changing its z-value (put it into background) etc.
438 \subsubsection*{Frames}
439 A frame can be added to a branch by clicking with the
440 right-mouse button. A context menu will open, where you can choose the
441 frame. At the moment just a rectangle resp. "No Frame" will be offered,
442 nevertheless you can use images as frames. Have a look at the demo map
443 {\tt todo.vym} as an example, where the mapcenter is a cloud. You can
444 use an external drawing program like {\tt gimp} to create an image,
445 preferable with an transparency channel, so that you can design frames
446 which don't use a rectangular borderline, just like the cloud.
449 \subsection{Background design}
450 The design of the background of a map and also of the links connecting
451 various parts of the map can be changed by
453 \item Selecting Format from the menu
454 \item Right clicking onto the canvas, which will open a context menu
457 \subsubsection*{Background color}
458 The color is set (and also displayed) as "Set background color".
460 \subsubsection*{Link color}
461 Links connecting branches can be colored in one of the following ways:
463 \item use the color of the heading of the branch the links is
464 \item use {\em one} color for all links. The default color is blue.
467 The latter can be set with "Set link color". Check or uncheck the "Use
468 color of heading for link" option to choose one of the two designs for
471 \subsubsection*{Link style}
472 \vym offers four different styles for the appearences of links:
479 The "thick" styles only draw links starting at mapcenter thick, the rest
480 of the map is always painted "thin".
483 \subsection{Links to other documents and webpages}
484 \vym supports two kind of external links:
486 \item Document, which will be opened in an external webbrowser
487 \item \vym map, which will be opened in \vym itself
489 In addition to the external links there also internal ones, leading from one
490 branch in a map toanother one. Those are called {\em XLinks} and are explained
491 in section~\ref{xlinks}.
493 \subsubsection*{Webbrowser}
494 Modern Webbrowsers like {\tt konqueror} are able to display various
495 types of files, both local or in the internet. To enter the URL of
496 any document, right-click onto a branch or use the Edit Menu
497 and choose "Edit URL". Enter the path to your document (or copy and
498 paste it from your browser). Examples for valid paths are:
500 http://www.insilmaril.de/vym/index.html
501 file:/usr/share/doc/packages/vym/doc/vym.pdf
503 If an URL was entered, a little globe will appear in the branch. By
504 clicking on the globe in the toolbar or the context menu an external
506 The browser can be changed in the Settings Menu.}
509 \includegraphics[width=0.5cm]{flag-url.png}
511 For more information on working with bookmarks and webbrowsers see
512 section \ref{bookmarks}.
515 \subsubsection*{\vym map}
516 To link to to another map right click on a branch or choose "Edit \ra
517 Enter \vym link". A file dialog opens where you can choose the map. A
518 branch with a link is marked with
520 \includegraphics[width=0.5cm]{flag-vymlink.png}
522 Clicking this flag in the toolbar or in the context menu of a branch
523 will open the map in another tab (see \ref{tabs} for working with
524 multiple maps). To delete an existing link, just press the "Cancel"
527 Technical note: Internally \vym uses absolute paths, to avoid opening
528 several tabs containing the same map. When a map is saved, this path is
529 converted to a relative one (e.g. {\tt /home/user/vym.map} might become
530 {\tt ./vym.map}. This makes it fairly easy to use multiple maps on
531 different computers or export them to HTML in future.
533 \subsection{Multiple maps} \label{tabs}
534 You can work on multiple maps at the same time. Each new map is opened
535 in another {\em tab}. The available tabs are shown just above the
536 mapeditor. You can use the normal cut/copy/paste functions to
537 copy data from one map to another.
542 %\subsubsection{Menus}
543 %\subsubsection{Keyboard shortcuts}
548 % Working with tabs (multiple maps)
552 \section{Noteeditor} \label {noteeditor}
553 If you want to save more text in a branch e.g. a complete email, a
554 cooking recipe, or the whole source code of a software project, you can
557 \includegraphics[width=8cm]{noteeditor.png}
559 This editor displays text associated to a branch selected in the
560 mapeditor. To visualize that there maybe is no text yet, the noteeditor
561 shows different background colors depending on its state:
564 Before you can type or paste text into it, you have
565 to select a branch in the mapeditor. Note that the background color
566 of the noteeditor indicates its state:
568 \item black: no branch selected
569 \item grey: no text entered yet
570 \item white: text is already available
572 To show you in the mapeditor itself that there is a note with more
573 information for a particular branch, a little note flag will appear next
574 to the heading of the branch. See the lower branch on the right side:
576 \includegraphics[width=8cm]{branches-flags.png}
579 \subsection{Import and export notes}
580 The note is always saved automatically within the \vym file itself.
581 Nevertheless sometimes it is nice to import a note from an external file
582 or write it. Use "File\ra~Import" and "File\ra~Export" to do so.
584 \subsection{Edit and print note}
585 Editing works like in any simple texteditor, including undo and redo
586 functions. You can delete the complete note by clicking the
587 trashcan. Only the note itself is printed by clicking the printer icon.
589 When pasting into the editor using the X11 copy\&paste mechanism, the
590 editor will create a paragraph for each new line. Usually this is not
591 wanted, so there you can convert all paragraphs into linebreaks by using
592 Edit~\ra~Remove~Paragraphs or \key{ALT-X}.
594 \subsection{RichText: Colors, paragraphs and formatted text}
595 \vym supports formatted text (QT Rich Text) in the noteeditor since
596 version 1.4.7. Colors and text attributes (e.g. italic, bold) can be
597 set with the buttons above the text. The text itself is divided in
598 paragraphs. For each paragraph the format can be set (e.g. centered,
599 right). A paragraph is ended when a \key{Return} is entered. If you just
600 want to begin a new line, press \key{CTRL-Return}.
602 \subsection{Fonts and how to quickly switch them}
603 The noteeditor is ment to be used for simple notes, not really as full
604 featured text editor. Because of many requests \vym supports now
605 formatted text in the noteeditor\footnote{
606 \vym uses the QRichtText format, which is basically a subset of the
607 formatting provided in HTML.}
608 Two default fonts are supported which can be set in the Settings menu.
609 One is a fixed width font, the other has variable width. The fixed font
610 is usually used for emails, source code etc.\ while the variable font is
611 used for simple notes, where one doesn't need fixed character widths.
612 Both fonts can easily switched using the following symbol from the
615 \includegraphics[width=0.5cm]{formatfixedfont.png}
617 In the Settings menu both fonts can be set and also which font should be
620 Additionally to the default fonts any font installed on your system can
621 be used. Please note, that the chosen font also will be used for HTML
622 exports, so you should only use fonts which are available generally.
624 \subsection{Find text}
625 The noteeditor itself has no Find function, use Find in the mapeditor,
626 which will also search all notes (see \ref{findwindow}).
628 \subsection{Paste text into note editor}
629 Often you will paste text into the editor from another application e.g.
630 an email. Normally \vym will generate a new paragraph for each new line.
631 This usually is not what you want, so you can choose from the menu
633 \subsection{Advanced actions}
634 \subsubsection*{Edit \ra Convert subsubsections:}
635 This turns subsubsections in selected text (or all text, if nothing is
636 selected) into linebreaks. This is especially useful for snippets of
639 \subsubsection*{Edit \ra Join Lines:}
640 Tries to format text, so that empty lines are used to delimit
641 paragraphs. This is done for selected text (or all text, if nothing is
642 selected). Especially useful for text like emails, meeting minutes etc.
644 \section{Hello world}
645 This section is about how \vym can interact with other applications.
646 Many applications meanwhile can read and write their data using XML, the
647 eXtensible Markup Language. \vym also uses XML to save its maps, see
648 \ref{fileformat} for a more detailed description.
650 So if your an application understands XML, chances are good that someone
651 could write import/export filters for \vym. Volunteers are always
654 \subsection{Import} \label{import}
656 \subsubsection*{KDE Bookmarks}
657 The integrated bookmark editor in KDE is somewhat limited, so why not
658 use \vym to maintain the bookmark mess? To create a new map containing
659 your current KDE bookmarks just choose
661 \item File \ra Import\ra KDE Bookmarks
664 \subsubsection*{Mind Manager}
665 \vym has currently a very basic import filter to convert maps created by
666 {\em Mind Manager}\footnote{Mind Manager is a professional software by
667 Mindjet. Both names are registered trademarks by Mindjet. For more
668 information see their website at
669 \href{http://mindjet.de}{http://mindjet.de}} into \vym maps. Notes and
670 pictures are not converted at the moment. You can import files with
672 \item File \ra Import\ra Mind Manager
676 \subsubsection*{Directory structure}
677 \vym can read a directory structure. This is mainly for
678 testing \vym e.g. to easily create huge maps used for benchmarks (yes,
679 there is still room to optimize \vym ;-)
684 \subsection{Export} \label{export}
686 Often you don't want to export the whole map, but just parts of it. For
687 example you may have additional info you want to talk about in a
688 presentation, while those parts should not be visible to the audience.
689 To achieve this you can "hide" parts of the map during exports by
690 setting the "hide in export" flag.
692 \includegraphics[width=0.5cm]{flag-hideexport.png}
694 You can toggle this flag in the toolbar or by pressing \key{H}.
695 Note that there is a global option in the settings menu to toggle the
696 use of this flag. By default the flag is enabled.
698 \subsubsection*{Open Office}
699 Open Office beginning with version~2 uses the so called "Open Office
700 Document Format", which can be written by \vym. The options are
701 currently limited, but it possible to export presentations which can be
702 opened in Open Office Impress. By selecting
704 \item File \ra Export\ra Open Office
706 you get a file dialogue where you can choose the output file and the
709 \includegraphics[width=12cm]{export-oo.png}
711 The file types represent various templates, which can be created with
712 some manual work from an existing Open Office document. The structure of
713 \vym map is then inserted into a template.
714 There are some limitations at the moment:
716 \item \vym can't take care of page lengths, so you have to check and
717 probably reedit in Open Office to avoid text running over the end of
719 \item Images and flags are not used at the moment
720 \item Notes are just written as plain text, without RichText
722 Some of the templates make use of {\em sections} e.g. insert the
723 headings of mainbranches as chapters for sections into the presentation.
725 \subsubsection*{Image}
726 \vym supports all image formats which are natively supported by the
728 BMP, JPEG, PBM, PGM, PNG, PPN, XPM, and XBM.
729 For use in websites and for sending images by email PNG is a good
730 recommodation regarding quality and size of the image. \vym uses QTs
731 default options for compressing the images.
733 \subsubsection*{ASCII}
734 Exporting an image as text is somewhat experimental at the moment. Later
735 this will probably done using stylesheets. So the output may change in
736 future versions of \vym.
738 \subsubsection*{\LaTeX}
739 \vym can generate an input file for \LaTeX. Currently this is considered
740 as experimental, there are no options (yet).
743 \item File \ra Export\ra \LaTeX
745 you will be asked in a file dialog for the name of the output file. This
746 file should be included in a \LaTeX document using command
748 \include{inputfile.tex}
751 \subsubsection*{KDE Bookmarks}
752 \vym will overwrite the KDE bookmarks file and then try to notify
753 running konquerors via DCOP of the changed file. \vym does not create a
756 \item File \ra Export \ra KDE Bookmarks
760 \subsubsection*{XHTML (Webpages)}
762 This is the format you want to use to create a webpage. For an example
763 have a look at the \vym homepage:
764 \href{http://www.InSilmaril.de/vym}{www.InSilmaril.de/vym}
766 Some explanation how this works:
767 Before a map is exported as XHTML, it will be first written as XML into a
768 directory (see \ref{xmlexport}). Then the external program {\tt
769 xsltproc}\footnote{On SUSE Linux {\tt xsltproc} is installed by
771 will be called to process the XML file and generate HTML code.
772 A dialog allows to set various options:
774 \item {\bf Include image:} If set, \vym will creat an image map at
775 the top of the HTML output. Clicking on a branch in the map will
776 jump to the corresponding section in the output.
778 \item {\bf Colored headings:}
779 If set to yes, \vym will color the headings in the text part with the
780 same colors like in the map.
781 \item {\bf Show Warnings:}
782 If set to yes, \vym will ask before overwriting data.
783 \item {\bf Show output:}
784 This is useful mainly for debugging. It will show how the processing of
785 the XML file works by calling the external {\tt xsltproc}.
787 Additionally the paths to the CSS and XSL stylesheets can be set. By
788 default on SUSE~Linux they will be in {\tt /usr/share/vym/styles}.
791 \subsubsection*{XML} \label{xmlexport}
792 The map is written into a directory both as an image and as XML. The
793 directory is set in a file dialog. If the directory is not empty, you
794 will be questioned if you risk to overwrite its contents.
796 It is possible to export different maps into the same directory. Each
797 file generated will have the map's name as prefix, e.g. {\tt todo.vym}
798 becomes {\tt todo.xml}, {\tt todo.png}, {\tt todo-image-1.png} and so
799 on. This is useful if e.g. for a website several combined maps have to
800 be stored in the same directory.
802 \subsubsection*{Export a part of a map}
803 Select a branch you want to export together with its childs, then open
804 the context menu and choose {\em Save Selection}. This will create a
805 file with the postfix {\tt .vyp}, which is an abbreviation for \lq vym
809 \section{Advanced Editing}
811 \subsection{How to deal with Bookmarks} \label{bookmarks}
812 \subsubsection*{Open new tabs instead of new windows}
813 If you use konqueror as browser, \vym will remember the konqueror which
814 was opened first by \vym. You can also press \key{Ctrl} and click to
815 open the link in a new tab then.
817 \vym can also open a new tab in Mozilla or Firefox using the remote
818 command\footnote{\href{http://www.mozilla.org/unix/remote.html}{http://www.mozilla.org/unix/remote.html}}
821 \subsubsection*{Drag and Drop}
822 If you want to keep bookmarks in a map, select a branch where you want
823 to add the bookmark, then simply drag the URL from your browser to the
824 map. Also you could use an existing heading as URL: Right click onto the
825 branch and select "Use heading for URL".
828 \subsubsection*{Directly access bookmark lists of a browser}
829 Please see the sections \ref{import} and \ref{export} about
830 Import and Export filters.
832 \subsubsection*{Special URLs}
833 \vym can turn an existing heading of a branch into an URL. Currently
834 this works for Bugentries in the Novell Bugtracking system: Open the
835 context menu of a branch (usually by right-clicking it) and select
837 \item Create URL to Bugzilla
839 The URL will be build from the number in the heading.
841 \subsection{Including images into a branch}
842 The default setting of an image is to float "freely". They can be
843 positioned everywhere, but they might end up in the same place as other
846 The solution is to include them "into" a branch. This can be done via
847 the context menu of their parent branch:
849 \item Include images horizontally
850 \item Include images vertically
852 The image ist still positioned relatively to its parent branch, but the
853 heading and border of the branch adapt to the floating image, see below:
855 \includegraphics[width=11cm]{includeImages.png}
858 \subsection{Modifier Modes}
859 Modifiers are for example the \key{Shift}- or the \key{Alt}-keys. When
860 pressed while doing actions with the mouse, they will cause \vym to use
861 a "modified" action. E.g. you can move branches with mouse. If
862 \key{Ctrl} or \key{Alt}is pressed while releasing the branch, it will be
863 added above/below the target, not as child of the target.
865 Without a modifier pressed, the first click on a branch just selects
866 it. For the behaviour of the \key{Ctrl} modifier there are several
867 options, which can be set from the modifier toolbar:
869 \includegraphics[width=3cm]{modmodes.png}
871 The default is to copy the color from the clicked branch to the already
872 selected branch. In the toolbar shown above the default modifier is
873 selected, namely to copy the color of a branch. The second modifier
874 let's you easily copy a whole branch with a single click. The third
875 modifier lets you create {\em xLinks}, which will be explained in the
878 \subsection{Hide links of unselected objects}
879 Sometimes it would be useful to position a branch freely, just like a
880 mainbranch or an image. Though this is not possible (yet) for all
881 branches, you can use a mainbranch and hide its connecting link to the
882 mapcenter. This can be used e.g. for legends or a collection of vymLinks
883 pointing to other maps:
885 \includegraphics[width=9cm]{hiddenlink.png}
889 \subsection{XLinks} \label{xlinks}
890 So far all the data in the \vym map has been treelike. Using xLinks you
891 can link one branch to any other, just like attaching a rope between two
892 branches in a real tree. This is especially useful in complex maps,
893 where you want to have crossreferences which don't fit on the same
894 visible area, which fits on your screen. The following example, which is
895 part of the \vym package, still fits on one screen, but shows how data
896 can be crosslinked. In the graphics there is a link from a task (prepare
897 a presentation) to general information:
899 \includegraphics[width=12cm]{xlink.png}
901 Note that a xLink which points to a branch that is not visible (because
902 it is scrolled), is just show as a little horizontal arrow. In the
903 screenshot above have a look at the \lq Tuesday\rq\ branch.
905 \subsubsection*{Create a xLink}
906 Choose the link mode from the modifier toolbar (by clicking or pressing
907 \key{L}). Select the branch, where the xLink should start. Press the
908 modifier key \key{Ctrl} and simultanously click on the branch where the
909 link should end. (The link is already drawn before you release the mouse
910 key). If you release the mouse over a branch the xLink becomes
913 \subsubsection*{Modify or delete a xLink}
914 Open the context menu of a branch and select \lq Edit xLink\rq. A
915 submenu contains all the xLinks of the branch (if there are any). They
916 are named like the branches, where they end. Choose one and
917 the xLink dialogue opens, where you can set color, width and also delete
920 \subsubsection*{Follow a xLink}
921 In a complext \vym map it sometimes comes handy to jump to the other end
922 of a xLink. You can do this by opening the context menu of the branch
923 and clicking on \lq Goto xLink\rq and selecting the xLink you want to
928 \subsection{Adding and removing branches}
929 The context menu of a branch shows some more ways to add and delete data
930 e.g. you can delete a branch while keeping its childs. The childs become
931 linked to the parent of the previously removed branch.
932 Similar branches can be inserted into existing maps. For keyboard
933 shortcuts also have a look at the context menu.
935 \subsection{Adding a whole map or a part of a map}
936 Select a branch where you want to add a previously saved map ({\tt .vym})or a part
937 of a map ({\tt .vyp}) , then open
938 the context menu and choose {\em Add \ra Import}. For the import you can
939 choose between {\em Import Add} and {\em Import Replace}: The imported
940 data will be added after the selection resp. replace the selection.
943 \section{\vym on Mac OS X}
944 \subsection{Overview}
945 Basically there are two ways to run \vym on Macs:
946 \subsubsection*{QT Mac Edition:}
947 \vym here provides the well known Mac look and feel. \vym is
948 available as zipped Mac OS X application. It has been compiled and
949 tested in Mac~OS~10.3, but should also work on Tiger. It is using
950 the Mac version of Trolltechs QT library.
952 \vym can also be run using the Linux version, but then menus and
953 handling will also be those of the Linux version e.g. The menu bar
956 \subsection {Contextmenu and special keys}
957 Most Macs unfortunatly just have a single mouse button. In order to show
958 the context menu which usually would be opened with the right mouse
959 button, you can click while pressing the \key{kommand}-key.
961 Especially on Laptops some of the keys usually used on PC keyboards seem
962 to be missing. The QT-Mac Edition of \vym has its own keyboard
963 shortcuts. To find the shortcuts just have a look at all the menu
964 entries, the shortcut is visible next to an entry. Toolbar buttons also
965 may have shortcuts, just position the mouse pointer over a button and
966 wait for the little help window to appear.
968 \subsection {Viewing external links}
969 \vym on Mac uses the system call {\tt /usr/bin/open} to view links.
970 Mac~OS determines automatically if the link is a pdf or www page and
971 opens the right browser.
976 \section{Starting \vym}
977 \subsection{Path to ressources}
978 \vym will try to find its ressources (images, stylesheets, filters,
979 etc.) in the following places:
981 \item Path given by the environment variable {\tt VYMHOME}.
982 \item If called with the local option (see \ref{options} below),
983 \vym will look for its data in the current directory.
984 \item {\tt /usr/share/vym}
985 \item {\tt /usr/local/share/vym}
988 \subsection{Command line options} \label{options}
989 \vym has the following options:
991 \begin{tabular}{ccp{8cm}}\\
992 \bf Option & \bf Comment & \bf Description \\ \hline
993 v & version & Show version ov \vym\\
994 l & local & Use local paths to stylesheets, translations, icons,
995 etc. instead of system paths. Useful for testing\\
996 h & help & Show help\\
997 q & quit & Quit immediatly after startup. Useful for benchmarks.\\
1000 You can also give several filenames at the commandline to let \vym open
1001 several maps at once.
1003 \section{Contributing to \vym}
1004 So far I'd say I have written 98\% of the code on my own. No surprise,
1005 that \vym exactly fits my own needs. Nevertheless I would like to
1006 encourage all users of \vym to contribute. Maybe not only with feature
1007 requests, but also with code, new import/export filters, translations
1008 etc. In this appendix I'll try to show how easy it is to expand the
1009 things you can do already with \vym. I really look forward to hear from
1012 \subsection{Getting help}
1014 \subsubsection*{Frequently asked questions}
1015 Please refer to the FAQ available on the \vym website:
1017 \href{http://www.InSilmaril.de/vym/faq.html}{http://www.InSilmaril.de/vym/faq.html}
1020 \subsubsection*{Mailinglists}
1021 There are two mailinglists: {\tt vym-forum} is the \vym users forum to
1022 discuss various questions, while {\tt vym-devel} is intended for people
1023 interested in contributing to \vym. You can view the archives and
1026 \href{https://sourceforge.net/mail/?group_id=127802}{https://sourceforge.net/mail/?group\_id=127802}
1029 \subsubsection*{Contacting the author}\label{author}
1030 Especially for support questions please try the mailinglists first. If
1031 everything else fails you can contact the Uwe Drechsel at
1033 \href{mailto:vym@InSilmaril.de}{vym@InSilmaril.de}
1038 \subsection{How to report bugs}
1039 Though Sourceforge has its own bugreporting system, I'd rather prefer if
1040 you contact me directly (see \ref{author}) or even better: You can file
1041 a bugreport in Bugzilla, the bugtracking system of openSUSE:
1043 \href{http://en.opensuse.org/Submit_a_bug}{http://en.opensuse.org/Submit\_a\_bug}
1045 I build \vym regulary for openSUSE, so you may report it against a
1046 recent version there, even if you use another Operating System.
1047 Please don't forget to tell
1049 \item the exact steps needed to reproduce the bug
1050 \item the version and build date of \vym (see the Help \ra About
1052 \item hardware and Operating System
1055 \subsection{Compiling from the sources}
1056 \subsubsection{Getting the sources} \label{getsources}
1057 You find the latest version of \vym at the project site:
1059 \href{https://sourceforge.net/projects/vym/}{https://sourceforge.net/projects/vym/}
1061 There you can check them out of the source repository (CVS):\\
1064 cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/vym checkout code
1067 \subsubsection{The Qt toolkit}
1068 Qt is C++ toolkit for multiplatform GUI and application development. It
1069 provides single-source portability across MS~Windows, Mac~OS~X, Linux
1070 ans all major commercial Unix variants. Qt is also available for
1071 embedded devices. Qt is a Trolltech product. For more information see
1073 \href{http://www.trolltech.com/qt/}{www.trolltech.com/qt}
1077 \subsubsection{Compiling \vym }
1078 Make sure you have installed your Qt environment properly, see the Qt
1079 documentation for details. You need to have the Qt command {\tt qmake}
1080 in your {\tt PATH}-environment, then run
1086 The last command {\tt make install} needs root-permissions. Of course it
1087 may be omitted, if you just want to test \vym.
1089 %\subsubsection*{Compiling \vym on Macs}
1092 \subsection{\vym file format} \label{fileformat}
1093 \vym maps usually have the postfix "{\tt .vym}" and represent a
1094 compressed archive of data. If you want to have a
1095 closer look into the data structure map called "mapname.vym",
1096 just uncompress the map manually using
1100 This will create directories named {\tt images} and {\tt flags} in your
1101 current directory and also the map itself, usually named {\tt
1103 The XML structure of \vym is pretty self explaining, just have a look at
1106 This XML file can be loaded directly into \vym, it does not have to be
1107 compressed. If you want to compress all the data yourself, use
1109 zip -r mapname.vym .
1111 to compress all data in your current directory.
1113 \subsection{New features}
1114 There are lots of features which might find their way into \vym.
1115 Together with \vym you should have received a directory with several
1116 maps e.g. on SUSE~LINUX this is
1118 {\tt /usr/share/doc/packages/vym/demos}
1120 where you find the map {\tt todo.vym}. It lists quite a lot of things to
1121 be done in future. If you have more ideas, contact the development team
1123 {\tt vym-devel@lists.sourceforge.net}.
1126 \subsection{New languages support}
1127 In order to add a new language to \vym you need
1128 the sources (see \ref{getsources}) and
1129 an installation of Trolltechs QT. A part of QT are the development
1130 tools, from those tools especially the translation tool "Linguist" is
1133 In some Linux distributions the development tools are in an extra package, e.g. on SUSE LINUX you should have installed:
1140 If you don't have QT in your system, you can get it from
1141 \href{http://www.trolltech.com}{http://www.trolltech.com} Once you
1142 are able to compile vym yourself, you can translate the text in vym
1143 itself by performing the following steps:
1145 \item Let's assume now your encoding is "NEW" instead of for example
1146 "de" for german or "en" for english
1148 \item Copy the file {\tt lang/vym\_en.ts} to l{\tt ang/vym\_NEW.ts} (The code
1149 itself contains the english version.)
1151 \item Add {\tt lang/vym\_NEW.ts} to the TRANSLATIONS section of vym.pro
1153 \item Run Linguist on {\tt vym\_NEW.ts} and do the translation
1155 \item Run {\tt lrelease} to create {\tt vym\_NEW.qm}
1157 \item Do a make install to install the new vym and check your translation
1160 If you feel brave, you can also translate the manual. It is written in
1161 LaTeX, you just have to change the file tex/vym.tex. (Linguist and QT
1162 are not needed, but it is useful to know how to work with LaTeX and esp.
1163 pdflatex to create the PDF.)
1165 Please mail me every translation you have done. I can also give you a
1166 developer access to the project, if you want to provide translations
1169 \subsection{New export/import filters}
1170 \vym supports various kinds of filters. Data can be written directly,
1171 inserted into templates or it can be written as XML data and then
1172 processed by XSL transformations.
1174 Most of the import/export functionality is available in the classes
1175 ImportBase and ExportBase and subclasses. All of them can be found in
1176 {\tt imports.h} and {\tt exports.h}.
1178 \subsubsection*{Direct import/export}
1179 An example for a direct export is the XML export. This method touches
1180 the implementation of nearly every object of \vym, so whenever possible
1181 you should better use a XSL transformation instead.
1183 If you still want to know how it is done, start looking at
1184 {\tt MapEditor::saveToDir} in {\tt mapeditor.cpp}.
1186 \subsubsection*{Templates}
1187 Templates have been introduced to export to opendoc format used e.g. by
1188 Open~Office. While I read the spec ($>$ 500 pages) about the format\footnote{
1189 \href{http://www.oasis-open.org/}{http://www.oasis-open.org/}}\
1190 I had the feeling that I did not want to write the export from scratch.
1191 It would be too complex to adapt the styles to your own wishes, e.g. the
1194 Instead I analyzed existing Open~Office documents. I found out that
1195 there are lots of redundant bits of information in a standard
1196 presentation, for example each list item is contained in its own list.
1197 In the end I came up with the default presentation style, which still
1198 could be simplified, just in case you have free time\ldots
1200 The existing templates are still work in progress, before you spent too
1201 much time developing your own style, please contact me. Basically the
1202 following steps are needed to build your own style:
1204 \item Create an example in Open Office. Use a title, authors name,
1205 page heading etc.\ which you can easily grep for in the output file.
1207 \item Unzip the Open Office document into a directory.
1209 \item The main file is called {\tt content.xml}. All data is in one
1210 single line. You can split the XML tags using the script {\tt
1211 scripts/niceXML}, which is part of the \vym distribution.
1213 \item Copy the output of {\tt niceXML} to {\tt
1214 content-template.xml}.
1216 \item Looking closer you will find lots of unused definitions, for
1217 example of styles. You can delete or simply ignore them.
1219 \item Try to find your title, authors name. \vym will replace the
1220 following strings while exporting:
1222 \begin{tabular}{lp{4cm}}
1223 {\tt <!-- INSERT TITLE -->} & title of map \\
1224 {\tt <!-- INSERT AUTHOR--> } & author \\
1225 {\tt <!-- INSERT COMMENT -->} & comment \\
1226 {\tt <!-- INSERT PAGES-->} & content of map \\
1229 The content itself is generated in a similar way by inserting lists
1230 into {\tt page-template}. Here the following substitutions are made:
1232 \begin{tabular}{lp{7cm}}
1233 {\tt <!-- INSERT PAGE HEADING-->} & heading of a page
1234 (mainbranch or child of mainbranch, depending on the use of
1236 {\tt <!-- INSERT LIST --> } & all childs of the branch above \\
1240 Currently images are exported and notes just will appear as text
1241 without formatting and colors.
1246 \subsubsection*{XSL Transformation}
1247 \vym uses XSL transformations while exporting (e.g. XHTML) and importing
1248 data (e.g. KDE bookmarks). There is a little code needed to provide the
1249 GUI, the rest is done using the {\tt .xsl} stylesheet and calling the
1250 {\tt xsltproc} processor, which is part of libxslt, the XSLT
1251 C library for GNOME.
1257 %\subsubsection{Menus}
1258 %\subsubsection{Keyboard shortcuts}
1259 %Where does vym save its settings? -> ~/.qt/vymrc