tex/vym.tex
 author insilmaril Thu, 06 Aug 2009 17:33:55 +0000 branch release-1-12-maintained changeset 76 a36a289372a6 parent 28 512536ce7773 permissions -rw-r--r--
Bugfix: Removed the 'new' in new branches to allow easier copy & paste
     1 \documentclass[12pt,a4paper]{article}

     2 \usepackage[utf8]{inputenc}

     3 \usepackage{verbatim}

     4 \usepackage{hyperref}

     5 \usepackage{graphicx}

     6 %\usepackage{longtable}

     7

     8 \setlength{\headheight}{0cm}

     9 \setlength{\headsep}{0cm}

    10 \setlength{\topskip}{0cm}

    11 \setlength{\topmargin}{-0.5cm}

    12

    13 \setlength{\parskip}{1.5ex}

    14 \setlength{\parindent}{0cm}

    15 \setlength{\oddsidemargin}{0cm}

    16 \setlength{\textwidth}{16cm}

    17 \setlength{\textheight}{27cm}

    18

    19 \newlength{\maximgwidth}

    20 \setlength{\maximgwidth}{14cm}

    21 \newcommand{\maximage}[1]{

    22 	\begin{center}

    23 		\includegraphics[width=\maximgwidth]{#1}

    24 	\end{center}

    25 }

    26 \newcommand{\hint}[1]{

    27 	\begin{center}

    28 		\begin{tabular}{|rp{12cm}|} \hline

    29 			{\bf Hint}:& #1\\	\hline

    30 		\end{tabular}

    31 			\marginpar{\Huge !}

    32 	\end{center}

    33 }

    34

    35 \newcommand{\vym}{{\sc vym }}

    36 \newcommand{\ra}{$\longrightarrow$}

    37 \newcommand{\la}{$\longleftarrow$}

    38 \newcommand{\ua}{$\uparrow$}

    39 \newcommand{\da}{$\downarrow$}

    40 \newcommand{\key}[1]{[#1]}

    41

    42 \newenvironment{code}[1] { \verbatim #1}{\endverbatim  }

    43

    44 \hypersetup{bookmarks, bookmarksopen,

    45   pdftitle={VYM - a tool for visual thinking },

    46   pdfauthor={Uwe Drechsel},

    47   pdfsubject={map},

    48   pdfkeywords={map, tool},

    49   pdfpagemode={UseOutlines},

    50   bookmarksopenlevel={1},

    51   colorlinks={true},

    52   linkcolor={blue},

    53   urlcolor={green},

    54   citecolor={red}}

    55

    56

    57 \begin{document}

    58 \title{

    59 	\includegraphics[width=8cm]{images/vym-logo-new.png}

    60 	\\

    61 VYM \\ -- \\View Your Mind\\ {\small Version 1.12.0}}

    62 \author{\textcopyright Uwe Drechsel  }

    63

    64

    65 \maketitle

    66

    67 \newpage

    68

    69 \tableofcontents

    70

    71 \newpage

    72

    73 \section*{Credits}

    74 Many people have sent me their feedback and ideas, and all of that has

    75 helped a lot to make \vym better. Thanks to all of you!

    76

    77 For this manual I would like to send some special thanks to

    78

    79 \begin{itemize}

    80 	\item {\em Peter Adamson} for lots of feedback and proofreading of my

    81 	      far from perfect english

    82 	\item The team of {\em AClibre (Academia y Conocimiento Libre)}

    83           in Colombia for their translation of

    84           the manual to spanish:

    85 		  \begin{center}

    86 			\begin{tabular}{|p{7cm}|p{5.5cm}|} \hline

    87 				Encargado & Actividad \\ \hline

    88 				\begin{itemize}

    89 				   \item Vanessa Carolina Guti\'errez Sanchez

    90 				   \item Erika Tatiana Luque Melo

    91 				   \item Jeffrey Steve Borb\'on Sanabria

    92 				   \item John Edisson Ortiz Rom\'an

    93 				\end{itemize} &

    94 				\begin{itemize}

    95 					\item Traducci\'onl

    96 					\item Revisi\'on y correcciones varias

    97 					\item Estructuraci\'on y exporte

    98 					\item Revisi\'on y correcciones varias

    99 				\end{itemize}     \\ \hline

   100 			\end{tabular}

   101 		\end{center}

   102 \end{itemize}

   103 \newpage

   104

   105

   106 \section{Introduction}

   107 \subsection{What is a \vym map?}

   108 A \vym map (abbreviated below as {\em map}) is a tree-like structure:

   109 \maximage{images/example1.png}

   110 Such maps can be drawn by hand on a sheet of paper or flip chart and help to

   111 structure your thoughts. While a tree like structure like the illustration above can be

   112 drawn manually \vym offers much more features to work with such maps.

   113 \vym is not just another drawing software application, but a tool to store and modify

   114 information in an intuitive way. For example you can reorder parts of

   115 the map by pressing a key or add various pieces of information like a complete

   116 email by a simple mouse click.

   117

   118 Once you have finished collecting and organising your ideas, you can

   119 easily generate a variety of outputs including for example a

   120 presentation in Open~Office based on a {\em map}.

   121

   122 \hint{You find the map shown above and others by clicking \begin{center}Help \ra Open vym

   123 examples\end{center} in the menu bar.}

   124

   125 \subsection{Why should I use {\em maps}? Time, Space and your Brain.}

   126 \subsubsection*{Space}

   127 A {\em map} can concentrate very complex content in a small space such as a

   128 piece of paper. It helps to use both sides of your brain: the logical

   129 side and also your creative side (e.g. by using pictures, colours and

   130 keywords in a map, often called {\em anchors}).  It is a technique to help

   131 organize the way you think and stimulate your creativity: It can help you by developing, sorting and helping to memorise your ideas.

   132

   133 \subsubsection*{Time}

   134 Because you just use keywords and drawings, it is much faster than good

   135 old fashioned 'notes'. Your brain memorizes things by associating them with

   136 other things -- a {\em map} makes use of those connections and stimulates

   137 new asccociations.

   138

   139

   140 \subsubsection*{Your Brain}

   141 In 1960 Prof. {\sc Roger Sperry} discovered that both hemispheres

   142 of the human brain undertake different tasks (of course both of them

   143 basically {\em can} do the same):

   144 \begin{center}

   145 \begin{tabular}{|p{5.5cm}|p{5.5cm}|} \hline

   146 	Left side & Right side \\ \hline

   147 	\begin{itemize}

   148 	   \item verbal speech and writing

   149 	   \item numbers

   150 	   \item logical thinking

   151 	   \item analysing and details

   152 	   \item science

   153 	   \item linear thinking

   154 	   \item concept of time

   155 	\end{itemize} &

   156 	\begin{itemize}

   157 		\item body language

   158 		\item visual thinking, day dreams

   159 		\item intuition and emotion

   160 		\item overview of things

   161 		\item creativity

   162 		\item art, music, dancing

   163 		\item non-linear thinking, connecting things

   164 		\item spatial awareness

   165 	\end{itemize}     \\ \hline

   166 \end{tabular}

   167 \end{center}

   168 In our science oriented western society we have learned to mainly rely on our

   169 left side of the brain, the "rational" one. In other cultures, such as the native americans and other "old" cultures, the right

   170 side is much more important. {\em Map} are just one way to stimulate the

   171 other side and make use of additional resources we all have.

   172

   173

   174 \subsection{Where could I use a {\em map}?}

   175 Here are some examples, how you can use those {\em maps}

   176 \begin{itemize}

   177     \item to prepare articles, papers, books, talks, \ldots

   178     \item to sort complex data

   179     \item to memorize facts, peoples names, vocabulary, \ldots

   180     \item to sort emails, files and bookmarks on your computer

   181     \item to moderate conferences

   182     \item to brainstorm solutions to problems

   183     \item to record the tasks when planning a project

   184 \end{itemize}

   185

   186 \subsection{What you shouldn't do with a {\em map}...}

   187 A {\em map} drawn by somebody shows the way that the author thinks. There is

   188 no question of right or wrong in the way it is drawn, so there is no way to criticise

   189 it. "It is, what it is" ({\sc F.~Lehmann}).The tool will be of considerable use to the author and only very limited use to anyone else.

   190

   191 However, when groups share in creating a {\em map} all of the group will benefit from its use. An example of such use is when a Tutor develops a {\em map} with a group of students during instruction. Another group use is when a Project leader gathers a group of specialists to help {\em map} the tasks that will be required to deliver a project.

   192

   193 %\section{Tutorials}

   194 %TODO

   195

   196 \subsection{Internet Ressources}

   197 A good starting point to learn more about Mindmaps in general is Wikipedia:

   198 \begin{itemize}

   199 	\item English:

   200 		\href{http://en.wikipedia.org/wiki/Mind_map}{http://en.wikipedia.org/wiki/Mind\_map}

   201 	\item German:

   202 		\href{http://de.wikipedia.org/wiki/Mindmap}{http://de.wikipedia.org/wiki/Mindmap}

   203 \end{itemize}

   204

   205

   206

   207

   208 \section{The Concept of the \vym application}

   209 %TODO may add a general introduction here...

   210 \subsection{The Mainwindow and its satellites} \label{satellite}

   211 \vym comes with several windows, the central one being the {\em

   212 mapeditor}.

   213 More windows, each having a special purpose, can be opened and arranged

   214 around the mainwindow\footnote{

   215 	The advantage of having separate window instead of integrating them

   216 	in a combined workspace is flexibility in arranging the windows. For

   217 	example I usually have the {\em noteeditor} "behind" the {\em

   218 	mapeditor}. On Linux my windowmanager (KDE) allows me to enter text

   219 	into a small visible corner of the {\em noteeditor} withour clicking

   220 	the mouse button in it. I just push the mouse around to set the

   221 	window focus, a concept which is useful also working with

   222 	\href{http://www.gimp.org}{http://www.gimp.org}.

   223 }.

   224 The image below shows the {\em mapeditor}

   225 together with the often used {\em noteeditor}:

   226 \maximage{images/windows.png}

   227 Most of the time you will work in the {\em mapeditor} by just adding new

   228 branches, moving around and reordering them. The various ways to do this

   229 will be explained in \ref{mapeditor}. You can store additional

   230 information e.g. the content of a email easily in a {\em branch}: Just

   231 type or copy\&paste it into the {\em noteeditor}. Working with notes is

   232 explained in \ref{noteeditor}

   233

   234 Here is a list of the available satellite windows:

   235 \begin{itemize}

   236 	\item Noteeditor (see \ref {noteeditor})

   237 	\item Historywindow (see \ref{historywindow})

   238 	\item Branch Property Window (see \ref{propwindow})

   239 \end{itemize}

   240

   241

   242 \subsection{Menus and Context menus}

   243 At the top of each window you will find the menubar. The options provided there

   244 are similar to those you are probably used to from other applications. Note that

   245 many (and even more) options are available via {\em context menus}. Those

   246 are available if you right-click onto an object in a map (on Mac~OS~X

   247 Command-Click).

   248

   249 \subsection{Toolbars}

   250 The toolbars in the mainwindows give quick access to many functions and

   251 also display the state of selected objects in the map. For example a

   252 branch may show certain {\em flags}, the corresponding flags are also

   253 set in the toolbar.

   254

   255 \hint {You can reposition all toolbars by simply grabbing and

   256 dragging them with the toolbar handle to a new position. For example you

   257 can move the flags-toolbar from its original horizontal position on top

   258 of the mapeditor to a vertical position on the right side.  Or just

   259 insert it again at its original position. Also hiding some of the

   260 toolbars is possible by right-clicking on the toolbar handle.}

   261

   262 \subsection{Maps}

   263 The  {\em map} itself has always a {\em mapcenter}.  The

   264 mapcenter has {\em branches} radiating out from the centre just like the trunk

   265 of a tree. Each branch in turn may have branches again.

   266 	\maximage{images/branches.png}

   267 We will call a branch directly connected to the mapcenter a {\em

   268 mainbranch}, because it determines the position of all its child

   269 branches.

   270

   271 The mapcenter and the branches all have a {\em heading}. This is the

   272 text you see in the mapeditor. Usually it should just be one or a few

   273 key words, so that one can easily keep track of the whole map.

   274

   275

   276 In the toolbar above the mapeditor you see various symbols.

   277 	\maximage{images/default-flags.png}

   278 These are called {\em flags} and can be used to mark branches in the

   279 {\em map}, e.g. if something is important or questionable.

   280 There are also more flags set by \vym automatically to show additional

   281 information, e.g. when a note is attached to a  particular branch.

   282

   283 By default some of these flags are set exclusively e.g. when the

   284 "thumb-up" flag is set, then the "thumb down" is reset and vice

   285 versa. You can change this default behaviour in the settings menu (see

   286 \ref{settings}).

   287

   288 \section{Mapeditor} \label {mapeditor}

   289 \subsection{Start a new map}

   290 After \vym is started two windows will open: the {\em mapeditor} and the {\em noteditor}. Usually you will work in both windows, but at the moment we

   291 will just need the mapeditor.

   292

   293 Select the mapcenter "New map" in the middle of the mapeditor by

   294 left-clicking with the mouse. It will be highlighted yellow to show that is

   295 selected. There are several ways to add a new branch to the center:

   296 \begin{itemize}

   297 	\item Using the mouse: Open the context menu by clicking with the

   298 	right mouse button (CTRL-Click on Mac) onto the

   299 	mapcenter and choose Add \ra Add branch as child

   300 	\item Press \key{Ins} or \key{A}

   301 \end{itemize}

   302 A new branch will appear and you will be able to type the heading of the

   303 branch. Finish adding the new branch by pressing \key{Enter}.

   304 %tipp

   305 Sometimes it comes in handy to be able to add a new branch above or below the current

   306 one.

   307 \begin{itemize}

   308 	\item Use \key{Shift-A} to add a branch above the selected one or...

   309 	\item \key{Ctrl-A} to add one below.

   310 \end{itemize}

   311 It is also

   312 possible to add a branch in such a way, that the current selection

   313 becomes the child of the new branch, which is like inserting it {\em

   314 before} the selection. This can be done using the context menu.

   315

   316 \hint{To delete a branch press \key{CTRL-X}. If enabled in the Settings

   317 menu (see \ref{settings}), you can also use the \key{Del} key.}

   318

   319 \subsection{Navigate through a map}

   320 \subsubsection*{Select branches}

   321 To select branches you can use the left button of your mouse or also the

   322 arrow keys. Depending on the {\em orientation} of a branch tap

   323 \key{\la} or \key{\ra} to move nearer to the mapcenter or deeper

   324 down into the branches. Within a set of branches, let's call them a

   325 {\em subtree}, you can use \key{PgUp} and \key{PgDn} to go up and down. You can

   326 also use \key{Home} and \key{End} to select the first and last branch.

   327

   328

   329 \subsubsection*{Panning the view of a map}

   330 While adding more and more branches the size of the map may become

   331 larger than the mapeditor window. You can use the scrollbars on the

   332 right and the bottom of your mapeditor window to scroll the view up or down or left or right. It is easier to just scroll using the left mouse button: Click anywhere on the {\em canvas} itself. Choose an empty space somewhere between the branches. The

   333 mouse pointer will change from an arrow to a hand, now move or drag the visible

   334 map to show the desired part.

   335

   336 If you select branches using the arrow keys, the map will scroll

   337 to ensure that the selected branch is always visible.

   338

   339 \subsubsection*{Zooming the view of a map}

   340 Working with huge maps, the {\em zoom}-function comes in handy: You can

   341 use

   342 \begin{itemize}

   343 	\item from the menu: View \ra Zoom in, View \ra Zoom out, View \ra reset Zoom.

   344 	\item the toolbar buttons

   345 		\begin{center}

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

   347 		\end{center}

   348 \end{itemize}

   349 Clicking the crossed magnifying lens icon will reset the zoomed view to its original size.

   350

   351

   352 \subsubsection*{Find Function} \label{findwindow}

   353 With huge maps there is the need to have a

   354 find function. Choose Edit \ra Find to open the Find Window:

   355 \begin{center}

   356 	\includegraphics[width=6cm]{images/find-window.png}

   357 \end{center}

   358 The find function will search for, the text you enter here, in all the branch headings and also in the associated notes. Everytime you press the "Find"-button it will look for the next occurence, which will then be selected automatically. If the search

   359 fails, a short message "Nothing found" will appear for a few

   360 seconds in the {\em statusbar} on the bottom of the mapeditor.

   361

   362 \subsubsection*{Keep the overview -- scroll a part of the map}

   363 A very big subtree of a map e.g. a branch with hundreds of child branches would make

   364 it very hard to keep an overview over the whole map. You can hide all

   365 the children of a branch by {\em scrolling} it -- this function is often called {\em folding}. Think of the whole subtree as painted onto a

   366 broadsheet newspaper. You can scroll or fold the paper to a small roll, leaving just

   367 the headline visible.

   368

   369 To scroll or unscroll a branch and its children,

   370 \begin{itemize}

   371 	\item press the \key{S}

   372 	\item press the middle-mouse button or

   373 	\item choose the scroll icon from the toolbar.

   374 \end{itemize}

   375 If you select parts of a scrolled branch e.g. using the find function or

   376 by using the arrow-keys, it will unscroll temporary. This is shown as a

   377 scroll with a little hour glass. If the temporary unscrolled part is no

   378 longer needed, it will be hidden again automatically. It is also

   379 possible to unscroll all branches using "Edit\ra Unscroll all scrolled

   380 branches".

   381

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

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

   384

   385 \subsection{Modify and move branches}

   386 \subsubsection*{Modify the heading}

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

   388 \begin{itemize}

   389 	\item pressing \key{Enter}

   390 	\item pressing \key{F2}

   391 	\item double-clicking with left mouse.

   392 \end{itemize}

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

   394

   395 \subsubsection*{Move a branch}

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

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

   398 Depending on the branch  it will be

   399 \begin{itemize}

   400 	\item moved to the destination or

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

   402 \end{itemize}

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

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

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

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

   407

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

   409 depend on the type of branch you are releasing:

   410 \begin{itemize}

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

   412 		It will stay on its new position.

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

   414 \end{itemize}

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

   416 overlapping of their subtrees.

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

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

   419 subtree by

   420 \begin{itemize}

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

   422 	\item selecting Edit \ra Move branch

   423 	\item clicking on the toolbar buttons:

   424 		\begin{center}

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

   426 		\end{center}

   427 \end{itemize}

   428 %tipp

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

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

   431 or below the one the mouse pointer is over. This can also be used to reorder branches in a map.

   432

   433 \subsection{Colours and Images - Using the right side of your brain}

   434 \subsubsection*{Change colour of a heading}

   435 You can also use colours to add more information to a map, e.g. use

   436 red, green and more colours to prioritize tasks. Again you can

   437 \begin{itemize}

   438 	\item use the menu and choose e.g Format \ra Set Color

   439 	\item use the toolbar

   440 		\begin{center}

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

   442 		\end{center}

   443 \end{itemize}

   444 The first button (black in the graphic above) shows the current colour.

   445 Clicking on it let's you choose another colour. You can also "pick"

   446 another colour by selecting a branch with the desired colour and using the

   447 "pick colour" button. Both of the icons showing a palette actually apply

   448 the current colour to the selected branch. While the first one just

   449 colours the heading of the selection, the last one also colours all the

   450 children of the selected branch.

   451

   452 %tipp

   453 A very useful function is the "copy colour" using the mouse: Select the

   454 branch which should get the new colour, then press \key{Ctrl} and

   455 simultanously click with left-mouse on another branch to copy its colour

   456 to the first one. Here the children of the selection also will get the new

   457 colour, if you just want to colour the selection itself, additionally

   458 press \key{Shift}.

   459

   460 \subsubsection*{Use flags}

   461 \vym provides various flags. They are usually displayed in the toolbar on top of the

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

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

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

   465 	\maximage{images/default-flags.png}

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

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

   468 always reflect the flags set in the selected branch. So, to remove a flag from a branch, select the branch and then click the highlighted flag on the toolbar.

   469

   470 At present \vym uses two kinds of flags: {\em System Flags} and {\em

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

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

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

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

   475

   476 \subsubsection*{Images}

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

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

   479

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

   481 branch. Right click the selected branch, choose "Add Image". A

   482 dialog window enables you choose the image to load.

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

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

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

   486 While an image is selected in the dialog, a preview of the

   487 image is displayed. It is also possible to select multiple images.

   488

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

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

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

   492

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

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

   495 to save the image.

   496

   497 Hint: This is used to "export" the image, it will be

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

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

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

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

   502

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

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

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

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

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

   508

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

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

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

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

   513

   514 \subsubsection*{Frames}

   515 A frame can be added to a branch in the {\em property window} (see

   516 \ref{propwindow}).

   517 Alternatively, you can use use images as frames. Have a look at the demo

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

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

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

   521 which don't use a rectangular borderline, just like that cloud.

   522

   523

   524 \subsection{Design of map background and connecting links }

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

   526 various parts of the map can be changed by

   527 \begin{itemize}

   528 	\item Selecting Format from the menu

   529 	\item Right clicking on the canvas, which will open a context menu

   530 \end{itemize}

   531

   532 \subsubsection*{Background }

   533 The colour is set (and also displayed) as "Set background colour".

   534 Alternatevily you can set an background image, though this is not

   535 recommended in general. Working on the map becomes slow and the image

   536 currently cannot be positioned freely.

   537

   538 \subsubsection*{Link colour}

   539 Links connecting branches can be coloured in one of two ways:

   540 \begin{itemize}

   541 	\item use the same colour for the heading and for the branch link line.

   542 	\item use {\em one} colour for all links and choose different colours for the branch headings text. The default colour for branch link lines is blue.

   543 \end{itemize}

   544 The latter can be set with "Set link colour". Check or uncheck the "Use

   545 colour of heading for link" option to toggle between the two designs for

   546 your map.

   547

   548 \subsubsection*{Link style}

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

   550 \begin{itemize}

   551 	\item Line

   552 	\item Parabel

   553 	\item Thick Line

   554 	\item Thick Parabel

   555 \end{itemize}

   556 The "thick" styles only apply to links starting at the mapcenter, link lines for the rest

   557 of the map are always painted "thin".

   558

   559

   560 \subsection{Links to other documents and webpages}

   561 \vym supports two kind of external links:

   562 \begin{itemize}

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

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

   565 \end{itemize}

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

   567 branch in a map to another one. Those are called {\em XLinks} and are explained

   568 in section~\ref{xlinks}.

   569

   570 \subsubsection*{Webbrowser}

   571 Modern Webbrowsers like {\tt konqueror and Firefox} are able to display various

   572 types of files, both local or on the internet. To enter the URL of

   573 any document, press \key{U} or right-click  onto a branch to open the contextmenu then choose

   574 "References\ra Edit URL". If you want to use a file dialog to

   575 conveniently choose a local file you can use~\key{U}.

   576

   577 After an URL was entered, a little globe will appear in the branch. By

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

   579 browser\footnote{

   580 	The browser can be changed in the Settings Menu (see \ref{settings}).}

   581 will be launched.

   582 \begin{center}

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

   584 \end{center}

   585 For more information on working with bookmarks and webbrowsers see

   586 section \ref{bookmarks}.

   587

   588 In the context menu there is also an option to open all URLs found

   589 in the selected subtree of the map. That's useful to simultanously open

   590 a collection of URLs in the webbrowser, especially if the browser can

   591 open them in tabs (like Konqueror).

   592

   593

   594 \subsubsection*{\vym map}

   595 To link to to another map right click on a branch and choose "Edit \vym link". A file dialog opens where you can choose the map. A

   596 branch with a link is marked with

   597 \begin{center}

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

   599 \end{center}

   600 Clicking this flag beside the branch heading, in the toolbar or in the context menu of a branch will open the map in another tab (see \ref{tabs} for working with

   601 multiple maps). To delete an existing link, just right click the branch and select "Delete \vym link".

   602

   603 In the context menu there is also an option to open all vymlinks found

   604 in the selected subtree of the map. That's useful to simultanously open

   605 a collection of related maps.

   606

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

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

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

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

   611 different computers or export them to HTML in future.

   612

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

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

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

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

   617 copy data from one map to another.

   618

   619 %todo

   620

   621 %TODO

   622 %\subsubsection{Menus}

   623 %\subsubsection{Keyboard shortcuts}

   624

   625 % Settings

   626 % Images

   627 % Copy & Paste

   628 % Working with tabs (multiple maps)

   629 % Exporting

   630 % Scrolling

   631

   632 \section{Noteeditor} \label {noteeditor}

   633 If you want to attach more text to a branch e.g. a complete email, a

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

   635 use the noteeditor.

   636 	\maximage{images/noteeditor.png}

   637 This editor displays text associated with a branch selected in the mapeditor. The noteeditor

   638 shows different background colours depending on whether text is associated with a selected branch.

   639

   640 \subsection{States}

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

   642 to select a branch in the mapeditor. Note that the background colour

   643 of the noteeditor indicates its state:

   644 \begin{itemize}

   645 	\item grey: no text entered yet

   646 	\item white: some text has been entered

   647 \end{itemize}

   648 In the mapeditor itself, to signal that there is a note with more

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

   650 to the heading of the branch. This is illustrated in the lower branch on the right hand side:

   651 	\maximage{images/branches-flags.png}

   652

   653 \subsection{Import and export notes}

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

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

   656 or write it. In the Note Editor use "File\ra~Import" and "File\ra~Export" to do so.

   657

   658 \subsection{Edit and print note}

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

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

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

   662

   663 \subsection{RichText: Colours, paragraphs and formatted text}

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

   665 version 1.4.7.  Colours and text attributes (e.g. italic, bold) can be

   666 set with the buttons above the text.

   667 %The text itself is divided into

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

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

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

   671

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

   673 The noteeditor is designed to be used for simple notes, not really as a full

   674 featured word processor. Because of many requests \vym supports

   675 formatted text in the noteeditor\footnote{

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

   677 	formatting provided in HTML.}

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

   679 (see \ref{settings}).

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

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

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

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

   684 toolbar:

   685 \begin{center}

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

   687 \end{center}

   688 In the Settings menu both fonts can be set. The default font can also be toggled between the fixed and variable font by selecting or deselecting the "fixed font is default" menu item.

   689

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

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

   692 exports, so if youy VYM mind map could ever be exported to a web or intranet page you should only use fonts which are available generally.

   693

   694 \subsection{Find text}

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

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

   697

   698 \subsection{Paste text into note editor}

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

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

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

   702

   703

   704 \section{Hello world}

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

   706 Many applications can now read and write their data using XML, the

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

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

   709

   710 So if you make use of another application that understands XML, chances are good that someone

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

   712 welcome ;-)

   713

   714 \subsection{Import} \label{import}

   715

   716 \subsubsection*{KDE Bookmarks}

   717 The integrated bookmark editor in KDE (Konqueror etc.) is somewhat limited, so why not

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

   719 your current KDE bookmarks just choose

   720 \begin{itemize}

   721 	\item File \ra Import\ra KDE Bookmarks

   722 \end{itemize}

   723

   724 \subsubsection*{Mind Manager}

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

   726 {\em Mind Manager}\footnote{Mind Manager is a commercial i.e. non free, software application by Mindjet for Windows and the Mac. Both names are registered trademarks by Mindjet. For more information see their website at

   727 \href{http://mindjet.com}{http://mindjet.com}} into \vym maps. Notes and

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

   729 \begin{itemize}

   730 	\item File \ra Import\ra Mind Manager

   731 \end{itemize}

   732

   733

   734 \subsubsection*{Directory structure}

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

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

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

   738

   739

   740

   741

   742 \subsection{Export}  \label{export}

   743 \label{hideexport}

   744 Often you may not want to export the whole map, but just parts of it. For

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

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

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

   748 setting the "hide in export" flag.

   749 \begin{center}

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

   751 \end{center}

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

   753 Note that there is a global option in the settings menu (

   754 \ref{settings}) to toggle the use of this flag. By default the flag is

   755 enabled.

   756

   757 \subsubsection*{Open Office}

   758 Open Office beginning with version~2 uses the so called "Open Document Format", which can be written by \vym. The options are

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

   760 opened in Open Office Impress. By selecting

   761 \begin{itemize}

   762 	\item File  \ra Export\ra Open Office

   763 \end{itemize}

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

   765 file type:

   766 	\maximage{images/export-oo.png}

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

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

   769 \vym map is then inserted into a template.

   770 There are some limitations at the moment:

   771 \begin{itemize}

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

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

   774 	a page

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

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

   777 	\item The full range of templates are not available in all distributions.

   778 \end{itemize}

   779 Some of the templates make use of {\em sections} i.e sections insert the

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

   781

   782 \subsubsection*{Image}

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

   784 QT~toolkit:

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

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

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

   788 default options for compressing the images.

   789

   790 \subsubsection*{ASCII}

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

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

   793 future versions of \vym.

   794

   795 \subsubsection*{\LaTeX}

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

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

   798 By selecting

   799 \begin{itemize}

   800 	\item File  \ra Export\ra \LaTeX

   801 \end{itemize}

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

   803 file may then be included in a \LaTeX document using command:

   804 \begin{verbatim}

   805 	\include{inputfile.tex}

   806 \end{verbatim}

   807

   808 \subsubsection*{KDE Bookmarks}

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

   810 running Konquerors via DCOP of the changed file. \vym does not create a

   811 backup!

   812 \begin{itemize}

   813 	\item File \ra Export \ra KDE Bookmarks

   814 \end{itemize}

   815

   816

   817 \subsubsection*{XHTML (Webpages)}

   818

   819 This is the format to use if you wish to create a webpage. To see an example

   820 visit the \vym homepage:

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

   822

   823 Some explanation on how this works:

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

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

   826 xsltproc}\footnote{On SUSE Linux and some other distributions {\tt xsltproc} is installed by

   827 default.}

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

   829 A dialog allows the user to set various options:

   830 \begin{itemize}

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

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

   833 	jump to the corresponding section in the output.

   834

   835 	\item {\bf Colored headings:}

   836 	If set to yes, \vym will colour the headings in the text part  with the

   837 	same colours used in the \vym map.

   838 	\item {\bf Show Warnings:}

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

   840 	\item {\bf Show output:}

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

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

   843 \end{itemize}

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

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

   846

   847

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

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

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

   851 will be warned and offered choices if you are at risk of overwriting existing contents.

   852

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

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

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

   856 on. This is useful if, for example, a website comprises several combined maps that have to be stored in the same directory.

   857

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

   859 Select a branch you want to export together with its children, then open

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

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

   862 part\rq.

   863

   864

   865 \section{Advanced Editing}

   866

   867 \subsection{Properties of an object}

   868 For any branch you can open a satellite window (see \ref{satellite}):

   869 the {\em property window}:

   870 \begin{center}

   871 	\includegraphics[width=8cm]{images/propwindow.png}

   872 	\label{propwindow}

   873 \end{center}

   874 %FIXME create screenshot

   875 %FIXME explain the tabs

   876

   877 \begin{itemize}

   878 	\item Frame

   879 	\item Link (see \ref{hideunselected})

   880 	\item Layout (see \ref{incimg})

   881 \end{itemize}

   882

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

   884 \vym keeps track of all changes done in a map. The default number of

   885 changes which can be undone is~75. The complete history can be seen in

   886 the {\em historywindow}:

   887 	\maximage{images/historywindow.png}

   888 	\label{historywindow}

   889 A single step back be undone or redone with \key{CTRL-Z} or \key{CTRL-Y},

   890 or by using the buttons in the toolbar or the {\em historywindow}.

   891 Inside the {\em historywindow}, you can click on a line to unwind all

   892 actions done until that point in time -- or redo all changes by clicking

   893 on the last line.

   894

   895 \hint{

   896 	You can "paste from the past": Go back in time by e.g. with

   897 	\key{CTRL-Z}, then copy to clipboard by pressing \key{CTRL-C}.

   898

   899 	Now do all actions again, e.g. by \key{CTRL-Y} or clicking on the

   900 	last action in {\em historywindow}. Now paste from the past with

   901 	\key{CTRL-V}.

   902 }

   903

   904 \subsection{Macros} \label{macros}

   905 Macros have been added to \vym in version~1.9.0.

   906 So far they have a preliminary character, maybe they are going to be

   907 replaced by full-featured scripting functionality later (though the

   908 commands will be more or less the same).

   909

   910 Each function key

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

   912 selection if the key is pressed. The default macros change the colour of

   913 a subtree or set the frame of a branch:

   914 \begin{center}

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

   916 \end{center}

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

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

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

   920 [\ref{settings})

   921 appendix~\ref{scripts}.

   922

   923 \subsection{Bookmarks} \label{bookmarks}

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

   925 If you use konqueror as your browser, \vym will remember the konqueror session which

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

   927 open the link in a new tab.

   928

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

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

   931 of these browsers.

   932

   933 \subsubsection*{Drag and Drop}

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

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

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

   937 branch and select "Use heading for URL".

   938

   939

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

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

   942 Import and Export filters.

   943

   944 \subsubsection*{Special URLs}

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

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

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

   948 \begin{itemize}

   949 	\item Create URL to Bugzilla

   950 \end{itemize}

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

   952

   953 \subsection{Associating images with a branch} \label{incimg}

   954 The default setting for an image is for it to float "freely". Images can be

   955 positioned anywhere on the canvas, but may end up in the same place as other

   956 parts of the map obscuring that part of the map.

   957

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

   959 the property window (see \ref{propwindow}):

   960 \begin{itemize}

   961 	\item Include images horizontally

   962 	\item Include images vertically

   963 \end{itemize}

   964 The image is still positioned relative to its parent branch, but the

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

   966 	\maximage{images/includeImages.png}

   967

   968 \subsection{Modifier Modes}

   969 Modifiers are for example the \key{Shift}- the \key{Ctrl}- ot the \key{Alt}-keys. When

   970 pressed while applying mouse actions, they will cause \vym to use

   971 a "modified" version of the action which usually would be done.

   972

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

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

   975

   976 Without a modifier key pressed, the first mouse click on a branch just selects

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

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

   979 \begin{center}

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

   981 \end{center}

   982 The default mode is to copy the colour from the clicked branch to the already

   983 selected branch. The figure above shows the toolbar with the default modifier

   984 selected. The second modifier

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

   986 modifier lets you create links between branches called {\em xLinks}.

   987 They will be explained in the next section \ref{xlinks}.

   988

   989 \subsection{Hide links of unselected objects} \label{hidelink}

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

   991 mainbranch or an image. This is possible for all

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

   993 mapcenter or hide the link between a child branch and its parent. This can be used e.g. for legends or a collection of vymLinks

   994 pointing to other maps:

   995 \begin{center}

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

   997 \end{center}

   998 To hide the link between a branch and its parent open the

   999 \ref{propwindow} and check "Hide link if object is not selected" on

  1000 "Link" tab.

  1001

  1002

  1003 \subsection{XLinks} \label{xlinks}

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

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

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

  1007 where you want to have crossreferences which can not be displayed on the same

  1008 visible area of the {\em mapeditor} window. The following example map still fits on one screen, but shows how data can be crosslinked. In the graphics there is a link from a task (prepare a presentation) to general information:

  1009 	\maximage{images/xlink.png}

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

  1011 it is scrolled), is just shown as a little horizontal arrow. In the

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

  1013

  1014 \subsubsection*{Create a xLink}

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

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

  1017 modifier key \key{Ctrl} and then click on the selected branch where the

  1018 link should start and drag the mouse pointer to the branch where the link is to end. (The link is drawn to follow the mouse pointer). When you release the mouse over a branch the xLink becomes permanent.

  1019

  1020 \subsubsection*{Modify or delete a xLink}

  1021 First select a branch at either end of the xLink. Then open the context

  1022 menu and select \lq Edit xLink\rq. A submenu contains all the xLinks of

  1023 the branch (if there are any). They are named like the branches, where

  1024 they end. Choose one and the xLink dialogue opens, where you can set

  1025 colour, width and also delete the xLink.

  1026

  1027 \subsubsection*{Follow a xLink}

  1028 In a complex \vym map it sometimes comes in handy to be able to jump to the other end

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

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

  1031 follow.

  1032

  1033

  1034

  1035 \subsection{Adding and removing branches}

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

  1037 e.g. you can delete a branch while keeping its children. The children become

  1038 linked to the parent of the previously removed branch.

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

  1040 shortcuts also have a look at the context menu.

  1041

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

  1043 Select a branch where you want to add a previously saved map ({\tt

  1044 .vym})or a part of a map ({\tt .vyp}) , then open the context menu and

  1045 choose {\em Add \ra Add Map (Insert)}. For the import you can choose

  1046 between {\em Add Map (Insert)} and {\em Add Map (Replace)}: The imported

  1047 data will be added after the selected branch.

  1048

  1049

  1050 \section{\vym on Mac OS X}

  1051 \subsection{Overview}

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

  1053 \subsubsection*{Qt Mac Edition:}

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

  1055 	available as Mac OS X application package in contained in a disk

  1056 	image ({\tt vym.dmg}. It has been compiled and tested in

  1057 	Mac~OS~10.4.  This package includes  runtime libraries of Qt by

  1058 	Trolltech.

  1059

  1060 \subsubsection*{X11 version} \vym can also be run using the Linux

  1061 version, but then menus and handling will also be those of the Linux

  1062 version e.g. The menu bar will look different.

  1063

  1064 \subsection	{Contextmenu and special keys}

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

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

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

  1068

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

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

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

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

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

  1074 wait for the little help window to appear.

  1075

  1076 \subsection {Viewing external links}

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

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

  1079 opens the right browser.

  1080

  1081

  1082 \newpage

  1083

  1084 \begin{appendix}

  1085

  1086 \section{\vym initialisation process and configuration}

  1087 \subsection {Settings menu}

  1088 	The {\em Settings} menu allows to configure \vym to your needs:

  1089

  1090 \subsubsection*{Set application to open PDF files} Choose a PDF

  1091 	viewer like {\tt acrobat} or {\tt konqueror} which is installed on

  1092 	your system.

  1093

  1094 \subsubsection*{Set application to open external links}

  1095 	Choose your favourite webbrowser here.

  1096

  1097 \subsubsection*{Set path for macros}

  1098 	Set the default search path for macros, which will be executed when

  1099 	you press one of the function keys. Each key corresponds to a file

  1100 	({\tt macro-1.vys..macro12.vys}) in the search path.

  1101

  1102 \subsubsection*{Set number of undo levels}

  1103 	Sets the number of undo/redo levels. The default setting is

  1104 	75~levels.

  1105

  1106 \subsubsection*{Autosave and autosave time}

  1107 	Automatic saving of modified maps can be toggled on or off. The

  1108 	autosave time is entered in seconds.

  1109

  1110 \subsubsection*{Write backup on save}

  1111 	When saving a map called {\tt example.vym}, \vym will rename the

  1112 	existing file to {\tt example.vym\~{}} before writing the {\tt

  1113 	example.vym} itself.

  1114

  1115 \subsubsection*{Edit branch after adding it}

  1116 	If set, the heading of a new branch will be edited immediatly after

  1117 	adding the branch.

  1118

  1119 \subsubsection*{Select branch after adding it}

  1120 	If set, a new branch will be selected immediatly after adding it.

  1121 	When you "brainstorm" on a given keyword, you don't want to go

  1122 	deeper and deeper into details, but keep the focus on the keyword.

  1123 	So the default setting here is to {\em not} select the freshly added

  1124 	branch.

  1125

  1126 \subsubsection*{Select existing heading}

  1127 	If set and you begin to edit the heading of a branch, the heading text in

  1128 	the dialog will be selected. Usefully to copy\&paste to other

  1129 	applications.

  1130

  1131 \subsubsection*{Delete key}

  1132 	If set, the \key{Delete} is enabled to, well, delete objects. This

  1133 	can be switched off to avoid confusing with the nearby

  1134 	\key{Insert}-key on PC keyboards.

  1135

  1136 \subsubsection*{Exclusive flags}

  1137 	If set, some of the standard flags can only be used exclusively,

  1138 	e.g.~the smileys.

  1139

  1140 \subsubsection*{Use hide flags}

  1141 	If set, every branch which also has the hide flag set (see

  1142 	\ref{hideexport}) will be hidden in exports.

  1143

  1144 \subsection{Configuration file}

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

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

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

  1148 directory. The exact position depends on the platform:

  1149 \begin{center}

  1150 \begin{tabular}{cl}

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

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

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

  1154 \end{tabular}

  1155 \end{center}

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

  1157 Editor (installed with xtools).

  1158

  1159 \subsection{Path to ressources}

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

  1161 etc.) in the following places:

  1162 \begin{enumerate}

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

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

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

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

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

  1168 \end{enumerate}

  1169

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

  1171 \vym has the following options:

  1172 \begin{center}

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

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

  1175 v & version &			& Show version and codename of \vym\\

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

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

  1178 h & help	&			& Show help\\

  1179 r & run 	& filename	& Load and run script\\

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

  1181 \end{tabular}

  1182 \end{center}

  1183 You can also give several filenames at the commandline to let \vym open

  1184 several maps at once.

  1185

  1186

  1187 \section{Scripts} \label{scripts}   %FIXME

  1188

  1189 TODO: This section of the \vym manual is not complete yet, sorry.

  1190

  1191 \subsection{Example scripts}

  1192 \subsubsection{Export a set of maps}

  1193 \begin{code}

  1194 \# Simple vym script to export images of various maps simultanously

  1195 exportImage ();

  1196 \end{code}

  1197 The script above can be used to export all maps in a directory

  1198 automatically. If the script is named {\tt export-image.vys}, call \vym with

  1199 \begin{code}

  1200 \$vym --quit --run export-image.vys *.vym   1201 \end{code}   1202   1203   1204 \section{Contributing to \vym}   1205 So far I'd say I have written 98\% of the code on my own. No surprise,   1206 that \vym exactly fits my own needs. Nevertheless I would like to   1207 encourage all users of \vym to contribute. Maybe not only with feature   1208 requests, but also with code, new import/export filters, translations   1209 etc. In this appendix I'll try to show how easy it is to expand the   1210 things you can do already with \vym. I really look forward to hear from   1211 you!   1212   1213 \subsection{Getting help}   1214   1215 \subsubsection*{Frequently asked questions}   1216 Please refer to the FAQ available on the \vym website:   1217 \begin{center}   1218 \href{http://www.InSilmaril.de/vym/faq.html}{http://www.InSilmaril.de/vym/faq.html}   1219 \end{center}   1220   1221 \subsubsection*{Mailinglists}   1222 There are two mailinglists: {\tt vym-forum} is the \vym users forum to   1223 discuss various questions, while {\tt vym-devel} is intended for people   1224 interested in contributing to \vym. You can view the archives and   1225 subscribe at   1226 \begin{center}   1227 \href{https://sourceforge.net/mail/?group_id=127802}{https://sourceforge.net/mail/?group\_id=127802}   1228 \end{center}   1229   1230 \subsubsection*{Contacting the author}\label{author}   1231 Especially for support questions please try the mailinglists first. If   1232 everything else fails you can contact the author Uwe Drechsel at   1233 \begin{center}   1234 \href{mailto:vym@InSilmaril.de}{vym@InSilmaril.de}   1235 \end{center}   1236   1237   1238   1239 \subsection{How to report bugs}   1240 Though Sourceforge has its own bugreporting system, I'd rather prefer if   1241 you contact me directly (see \ref{author}) or even better: You can file   1242 a bugreport in Bugzilla, the bugtracking system of openSUSE:   1243 \begin{center}   1244 \href{http://en.opensuse.org/Submit_a_bug}{http://en.opensuse.org/Submit\_a\_bug}   1245 \end{center}   1246 I build \vym regulary for openSUSE, so you may report it against a   1247 recent version there, even if you use another Operating System.   1248 Please don't forget to tell me what you are using:   1249 \begin{itemize}   1250 \item the exact steps needed to reproduce the bug   1251 \item the version and build date of \vym (see the Help \ra About   1252 \vym)   1253 \item hardware and Operating System   1254 \end{itemize}   1255   1256 \subsection{Compiling from the sources}   1257 \subsubsection{Getting the sources} \label{getsources}   1258 You find the latest version of \vym at the project site:   1259 \begin{center}   1260 \href{https://sourceforge.net/projects/vym/}{https://sourceforge.net/projects/vym/}   1261 \end{center}   1262 There you can check them out of the source repository (CVS):\\   1263   1264 \begin{verbatim}   1265 cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/vym checkout code   1266 \end{verbatim}   1267   1268 \subsubsection{The Qt toolkit}   1269 Qt is C++ toolkit for multiplatform GUI and application development. It   1270 provides single-source portability across MS~Windows, Mac~OS~X, Linux   1271 and all major commercial Unix variants. Qt is also available for   1272 embedded devices. Qt is a Trolltech product. For more information see   1273 \begin{center}   1274 \href{http://www.trolltech.com/qt/}{www.trolltech.com/qt}   1275 \end{center}   1276   1277   1278 \subsubsection{Compiling \vym }   1279 Make sure you have installed your Qt environment properly, see the Qt   1280 documentation for details. You need to have the Qt command {\tt qmake}   1281 in your {\tt PATH}-environment, then run   1282 \begin{code}   1283 \$ qmake

  1284 $make   1285$ make install

  1286 \end{code}

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

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

  1289

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

  1291 %FIXME

  1292

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

  1294 \vym maps usually have the suffix "{\tt .vym}" and represent a

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

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

  1297 just uncompress the map manually using

  1298 \begin{code}

  1299 \$unzip mapname.vym   1300 \end{code}   1301 This will create directories named {\tt images} and {\tt flags} in your   1302 current directory and also the map itself, usually named {\tt   1303 mapname.xml}.   1304 The XML structure of \vym is pretty self explaining, just have a look at   1305 {\tt mapname.xml}.   1306   1307 This XML file can be loaded directly into \vym, it does not have to be   1308 compressed. If you want to compress all the data yourself, use   1309 \begin{code}   1310 \$ zip -r mapname.vym .

  1311 \end{code}

  1312 to compress all data in your current directory.

  1313

  1314 \subsection{New features}

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

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

  1317 example maps. You find them by clicking Help \ra Open~vym~example~maps.

  1318 There you will find the map {\tt vym-projectplan.vym}. It lists quite a

  1319 lot of things to be done in future. If you have more ideas, contact the

  1320 development team at {\tt vym-devel@lists.sourceforge.net}.

  1321

  1322

  1323 \subsection{New languages support}

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

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

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

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

  1328 needed.

  1329

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

  1331 \begin{code}

  1332 libqt4-devel.rpm

  1333 libqt4-devel-doc.rpm

  1334 libqt4-devel-tools.rpm

  1335 \end{code}

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

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

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

  1339 	itself by performing the following steps:

  1340 \begin{itemize}

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

  1342 	"de" for german or "en" for english

  1343

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

  1345 	itself contains the english version.)

  1346

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

  1348

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

  1350

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

  1352

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

  1354 \end{itemize}

  1355

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

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

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

  1359 pdflatex to create the PDF.)

  1360

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

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

  1363 regulary.

  1364

  1365 \subsection{New export/import filters}

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

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

  1368 processed by XSL transformations.

  1369

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

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

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

  1373

  1374 \subsubsection*{Direct import/export}

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

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

  1377 you should better use a XSL transformation instead.

  1378

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

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

  1381

  1382 \subsubsection*{Templates}

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

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

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

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

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

  1388 layout.

  1389

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

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

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

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

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

  1395

  1396 The existing templates are still work in progress, before you spend too

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

  1398 following steps are needed to build your own style:

  1399 \begin{enumerate}

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

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

  1402

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

  1404

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

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

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

  1408

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

  1410 	content-template.xml}.

  1411

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

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

  1414

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

  1416 	following strings while exporting:

  1417 	\begin{center}

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

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

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

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

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

  1423 	\end{tabular}

  1424 	\end{center}

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

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

  1427 	\begin{center}

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

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

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

  1431 		sections) \\

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

  1433 	\end{tabular}

  1434 	\end{center}

  1435 \end{enumerate}

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

  1437 without formatting and colours.

  1438

  1439

  1440

  1441

  1442 \subsubsection*{XSL Transformation}

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

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

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

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

  1447 C  library  for  GNOME.

  1448

  1449 \end{appendix}

  1450 \end{document}

  1451

  1452 %TODO

  1453 %\subsubsection{Menus}

  1454 %\subsubsection{Keyboard shortcuts}

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

  1456

  1457

  1458 % INDEX

  1459 % mapeditor

  1460 % noteditor

  1461 % branch

  1462 % mapcenter

  1463 % heading

  1464 % flag

  1465 % orientation

  1466 % zoom

  1467 % orientation

  1468 % Toolbar

  1469 % Zoom

  1470 % Find

  1471 % statusbar

  1472 % link

  1473 % mainbranch

  1474 % subtree

  1475 % reorder

  1476 % scroll

  1477 % fold

  1478 % vymlink

  1479 % xlink

  1480 % modMode

  1481 % context menu

  1482 % Mac OS X

  1483

  1484

  1485

  1486 \end{document}