
insilmaril@509: \documentclass[12pt,a4paper]{article}
insilmaril@509: \usepackage[utf8]{inputenc}
insilmaril@28: \usepackage{verbatim}
insilmaril@28: \usepackage{hyperref}
insilmaril@28: \usepackage{graphicx}
insilmaril@493: %\usepackage{longtable}
insilmaril@28: 
insilmaril@509: \setlength{\headheight}{0cm}
insilmaril@509: \setlength{\headsep}{0cm}
insilmaril@509: \setlength{\topskip}{0cm}
insilmaril@509: \setlength{\topmargin}{-0.5cm}
insilmaril@509: 
insilmaril@509: \setlength{\parskip}{1.5ex}
insilmaril@509: \setlength{\parindent}{0cm}
insilmaril@509: \setlength{\oddsidemargin}{0cm}
insilmaril@509: \setlength{\textwidth}{16cm}
insilmaril@509: \setlength{\textheight}{27cm}
insilmaril@509: 
insilmaril@509: \newlength{\maximgwidth}
insilmaril@509: \setlength{\maximgwidth}{14cm}
insilmaril@509: \newcommand{\maximage}[1]{	
insilmaril@509: 	\begin{center}
insilmaril@509: 		\includegraphics[width=\maximgwidth]{#1} 
insilmaril@509: 	\end{center}
insilmaril@509: }
insilmaril@509: \newcommand{\hint}[1]{
insilmaril@514: 	\begin{center} 
insilmaril@509: 		\begin{tabular}{|rp{12cm}|} \hline
insilmaril@509: 			{\bf Hint}:& #1\\	\hline
insilmaril@509: 		\end{tabular}
insilmaril@514: 			\marginpar{\Huge !} 
insilmaril@514: 	\end{center} 
insilmaril@509: }
insilmaril@509: 
insilmaril@509: \newcommand{\vym}{{\sc vym }}
insilmaril@509: \newcommand{\ra}{$\longrightarrow$}
insilmaril@509: \newcommand{\la}{$\longleftarrow$}
insilmaril@509: \newcommand{\ua}{$\uparrow$}
insilmaril@509: \newcommand{\da}{$\downarrow$}
insilmaril@509: \newcommand{\key}[1]{[#1]}
insilmaril@509: 
insilmaril@514: \newenvironment{code}[1] { \verbatim #1}{\endverbatim  }
insilmaril@514: 
insilmaril@28: \hypersetup{bookmarks, bookmarksopen,
insilmaril@28:   pdftitle={VYM - a tool for visual thinking },
insilmaril@28:   pdfauthor={Uwe Drechsel},    
insilmaril@28:   pdfsubject={map},
insilmaril@28:   pdfkeywords={map, tool},
insilmaril@28:   pdfpagemode={UseOutlines},                                 
insilmaril@28:   bookmarksopenlevel={1},   
insilmaril@28:   colorlinks={true},     
insilmaril@28:   linkcolor={blue},
insilmaril@28:   urlcolor={green},
insilmaril@28:   citecolor={red}} 
insilmaril@28: 
insilmaril@28: 
insilmaril@28: \begin{document}
insilmaril@233: \title{
insilmaril@450: 	\includegraphics[width=8cm]{images/vym-logo-new.png}
insilmaril@233: 	\\
insilmaril@589: VYM \\ -- \\View Your Mind\\ {\small Version 1.10.0}}
insilmaril@28: \author{\textcopyright Uwe Drechsel  }
insilmaril@28: 
insilmaril@233: 
insilmaril@28: \maketitle
insilmaril@28: 
insilmaril@233: \newpage
insilmaril@233: 
insilmaril@28: \tableofcontents
insilmaril@28: 
insilmaril@28: \newpage
insilmaril@28: 
insilmaril@540: \section*{Credits}
insilmaril@540: Many people have sent me their feedback and ideas, and all of that has
insilmaril@540: helped a lot to make \vym better. Thanks to all of you!
insilmaril@540: 
insilmaril@540: For this manual I would like to send some special thanks to
insilmaril@540: 
insilmaril@540: \begin{itemize}
insilmaril@540: 	\item {\em Peter Adamson} for lots of feedback and proofreading of my
insilmaril@540: 	      far from perfect english
insilmaril@540: 	\item The team of {\em AClibre (Academia y Conocimiento Libre)}
insilmaril@540:           in Colombia for their translation of
insilmaril@540:           the manual to spanish:
insilmaril@540: 		  \begin{center}
insilmaril@540: 			\begin{tabular}{|p{7cm}|p{5.5cm}|} \hline
insilmaril@540: 				Encargado & Actividad \\ \hline
insilmaril@540: 				\begin{itemize}
insilmaril@540: 				   \item Vanessa Carolina Guti\'errez Sanchez
insilmaril@540: 				   \item Erika Tatiana Luque Melo
insilmaril@540: 				   \item Jeffrey Steve Borb\'on Sanabria
insilmaril@540: 				   \item John Edisson Ortiz Rom\'an
insilmaril@540: 				\end{itemize} &
insilmaril@540: 				\begin{itemize}
insilmaril@540: 					\item Traducci\'onl
insilmaril@540: 					\item Revisi\'on y correcciones varias
insilmaril@540: 					\item Estructuraci\'on y exporte
insilmaril@540: 					\item Revisi\'on y correcciones varias
insilmaril@540: 				\end{itemize}     \\ \hline
insilmaril@540: 			\end{tabular}	
insilmaril@540: 		\end{center}
insilmaril@540: \end{itemize}
insilmaril@540: \newpage
insilmaril@540: 
insilmaril@540: 
insilmaril@28: \section{Introduction}
insilmaril@28: \subsection{What is a \vym map?}
insilmaril@640: A \vym map (abbreviated below as {\em map}) is a tree-like structure:
insilmaril@509: \maximage{images/example1.png}
insilmaril@486: Such maps can be drawn by hand on a sheet of paper or flip chart and help to
insilmaril@486: structure your thoughts. While a tree like structure like the illustration above can be
insilmaril@264: drawn manually \vym offers much more features to work with such maps.
insilmaril@486: \vym is not just another drawing software application, but a tool to store and modify
insilmaril@264: information in an intuitive way. For example you can reorder parts of
insilmaril@486: the map by pressing a key or add various pieces of information like a complete
insilmaril@264: email by a simple mouse click.
insilmaril@264: 
insilmaril@486: Once you have finished collecting and organising your ideas, you can
insilmaril@509: easily generate a variety of outputs including for example a
insilmaril@509: presentation in Open~Office based on a {\em map}.
insilmaril@509: 
insilmaril@509: \hint{You find the map shown above and others by clicking \begin{center}Help \ra Open vym
insilmaril@509: examples\end{center} in the menu bar.}
insilmaril@28: 
insilmaril@486: \subsection{Why should I use {\em maps}? Time, Space and your Brain.}
insilmaril@28: \subsubsection*{Space}
insilmaril@486: A {\em map} can concentrate very complex content in a small space such as a
insilmaril@28: piece of paper. It helps to use both sides of your brain: the logical
insilmaril@486: side and also your creative side (e.g. by using pictures, colours and
insilmaril@486: keywords in a map, often called {\em anchors}).  It is a technique to help
insilmaril@486: organize the way you think and stimulate your creativity: It can help you by developing, sorting and helping to memorise your ideas. 
insilmaril@28: 
insilmaril@28: \subsubsection*{Time}
insilmaril@28: Because you just use keywords and drawings, it is much faster than good
insilmaril@486: old fashioned 'notes'. Your brain memorizes things by associating them with
insilmaril@486: other things -- a {\em map} makes use of those connections and stimulates
insilmaril@28: new asccociations. 
insilmaril@28: 
insilmaril@125: 
insilmaril@28: \subsubsection*{Your Brain}
insilmaril@486: In 1960 Prof. {\sc Roger Sperry} discovered that both hemispheres
insilmaril@486: of the human brain undertake different tasks (of course both of them
insilmaril@125: basically {\em can} do the same): 
insilmaril@125: \begin{center}
insilmaril@125: \begin{tabular}{|p{5.5cm}|p{5.5cm}|} \hline
insilmaril@125: 	Left side & Right side \\ \hline
insilmaril@125: 	\begin{itemize}
insilmaril@125: 	   \item verbal speech and writing 
insilmaril@125: 	   \item numbers
insilmaril@125: 	   \item logical thinking
insilmaril@486: 	   \item analysing and details
insilmaril@125: 	   \item science
insilmaril@125: 	   \item linear thinking
insilmaril@125: 	   \item concept of time
insilmaril@125: 	\end{itemize} &
insilmaril@125: 	\begin{itemize}
insilmaril@125: 		\item body language
insilmaril@125: 		\item visual thinking, day dreams
insilmaril@125: 		\item intuition and emotion
insilmaril@125: 		\item overview of things
insilmaril@125: 		\item creativity
insilmaril@125: 		\item art, music, dancing
insilmaril@125: 		\item non-linear thinking, connecting things
insilmaril@125: 		\item spatial awareness
insilmaril@125: 	\end{itemize}     \\ \hline
insilmaril@125: \end{tabular}	
insilmaril@125: \end{center}
insilmaril@486: In our science oriented western society we have learned to mainly rely on our
insilmaril@486: left side of the brain, the "rational" one. In other cultures, such as the native americans and other "old" cultures, the right
insilmaril@486: side is much more important. {\em Map} are just one way to stimulate the
insilmaril@486: other side and make use of additional resources we all have.
insilmaril@28: 
insilmaril@28: 
insilmaril@486: \subsection{Where could I use a {\em map}?}
insilmaril@486: Here are some examples, how you can use those {\em maps}
insilmaril@28: \begin{itemize}
insilmaril@28:     \item to prepare articles, papers, books, talks, \ldots
insilmaril@28:     \item to sort complex data
insilmaril@486:     \item to memorize facts, peoples names, vocabulary, \ldots
insilmaril@28:     \item to sort emails, files and bookmarks on your computer
insilmaril@28:     \item to moderate conferences
insilmaril@486:     \item to brainstorm solutions to problems
insilmaril@486:     \item to record the tasks when planning a project
insilmaril@28: \end{itemize}
insilmaril@28: 
insilmaril@486: \subsection{What you shouldn't do with a {\em map}...}
insilmaril@486: A {\em map} drawn by somebody shows the way that the author thinks. There is
insilmaril@486: no question of right or wrong in the way it is drawn, so there is no way to criticise
insilmaril@486: 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. 
insilmaril@486: 
insilmaril@486: 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.
insilmaril@28: 
insilmaril@28: %\section{Tutorials}
insilmaril@28: %TODO
insilmaril@28: 
insilmaril@125: \subsection{Internet Ressources} 
insilmaril@486: A good starting point to learn more about Mindmaps in general is Wikipedia:
insilmaril@125: \begin{itemize}
insilmaril@125: 	\item English: 
insilmaril@125: 		\href{http://en.wikipedia.org/wiki/Mind_map}{http://en.wikipedia.org/wiki/Mind\_map}
insilmaril@125: 	\item German: 
insilmaril@125: 		\href{http://de.wikipedia.org/wiki/Mindmap}{http://de.wikipedia.org/wiki/Mindmap}
insilmaril@125: \end{itemize}
insilmaril@125: 
insilmaril@28: 
insilmaril@245: 
insilmaril@245: 
insilmaril@486: \section{The Concept of the \vym application}
insilmaril@28: %TODO may add a general introduction here...
insilmaril@493: \subsection{The Mainwindow and its satellites} \label{satellite}
insilmaril@493: \vym comes with several windows, the central one being the {\em
insilmaril@493: mapeditor}.
insilmaril@493: More windows, each having a special purpose, can be opened and arranged
insilmaril@493: around the mainwindow\footnote{
insilmaril@493: 	The advantage of having separate window instead of integrating them
insilmaril@493: 	in a combined workspace is flexibility in arranging the windows. For
insilmaril@493: 	example I usually have the {\em noteeditor} "behind" the {\em
insilmaril@493: 	mapeditor}. On Linux my windowmanager (KDE) allows me to enter text
insilmaril@493: 	into a small visible corner of the {\em noteeditor} withour clicking
insilmaril@493: 	the mouse button in it. I just push the mouse around to set the
insilmaril@493: 	window focus, a concept which is useful also working with 
insilmaril@493: 	\href{http://www.gimp.org}{http://www.gimp.org}.
insilmaril@493: }. 
insilmaril@493: The image below shows the {\em mapeditor}
insilmaril@493: together with the often used {\em noteeditor}: 
insilmaril@509: \maximage{images/windows.png}
insilmaril@486: Most of the time you will work in the {\em mapeditor} by just adding new
insilmaril@28: branches, moving around and reordering them. The various ways to do this
insilmaril@28: will be explained in \ref{mapeditor}. You can store additional
insilmaril@28: information e.g. the content of a email easily in a {\em branch}: Just
insilmaril@28: type or copy\&paste it into the {\em noteeditor}. Working with notes is
insilmaril@28: explained in \ref{noteeditor}
insilmaril@420:  
insilmaril@493: Here is a list of the available satellite windows:
insilmaril@493: \begin{itemize}
insilmaril@493: 	\item Noteeditor (see \ref {noteeditor})
insilmaril@493: 	\item Historywindow (see \ref{historywindow})
insilmaril@493: 	\item Branch Property Window (see \ref{propwindow})
insilmaril@493: \end{itemize}
insilmaril@493: 
insilmaril@28: 
insilmaril@245: \subsection{Menus and Context menus}
insilmaril@486: At the top of each window you will find the menubar. The options provided there
insilmaril@486: are similar to those you are probably used to from other applications. Note that
insilmaril@640: many (and even more) options are available via {\em context menus}. Those
insilmaril@245: are available if you right-click onto an object in a map (on Mac~OS~X
insilmaril@245: Command-Click).
insilmaril@245: 
insilmaril@245: \subsection{Toolbars}
insilmaril@245: The toolbars in the mainwindows give quick access to many functions and
insilmaril@493: also display the state of selected objects in the map. For example a
insilmaril@493: branch may show certain {\em flags}, the corresponding flags are also
insilmaril@493: set in the toolbar. 
insilmaril@245: 
insilmaril@509: \hint {You can reposition all toolbars by simply grabbing and
insilmaril@493: dragging them with the toolbar handle to a new position. For example you
insilmaril@493: can move the flags-toolbar from its original horizontal position on top
insilmaril@493: of the mapeditor to a vertical position on the right side.  Or just
insilmaril@493: insert it again at its original position. Also hiding some of the
insilmaril@509: toolbars is possible by right-clicking on the toolbar handle.}
insilmaril@245: 
insilmaril@245: \subsection{Maps}
insilmaril@486: The  {\em map} itself has always a {\em mapcenter}.  The
insilmaril@509: mapcenter has {\em branches} radiating out from the centre just like the trunk 
insilmaril@509: of a tree. Each branch in turn may have branches again.
insilmaril@509: 	\maximage{images/branches.png}
insilmaril@28: We will call a branch directly connected to the mapcenter a {\em
insilmaril@28: mainbranch}, because it determines the position of all its child
insilmaril@28: branches.
insilmaril@28: 
insilmaril@28: The mapcenter and the branches all have a {\em heading}. This is the
insilmaril@28: text you see in the mapeditor. Usually it should just be one or a few
insilmaril@486: key words, so that one can easily keep track of the whole map.
insilmaril@28: 
insilmaril@28: 
insilmaril@28: In the toolbar above the mapeditor you see various symbols.
insilmaril@509: 	\maximage{images/default-flags.png}
insilmaril@28: These are called {\em flags} and can be used to mark branches in the
insilmaril@486: {\em map}, e.g. if something is important or questionable. 
insilmaril@28: There are also more flags set by \vym automatically to show additional
insilmaril@486: information, e.g. when a note is attached to a  particular branch.
insilmaril@28: 
insilmaril@260: By default some of these flags are set exclusively e.g. when the 
insilmaril@486: "thumb-up" flag is set, then the "thumb down" is reset and vice
insilmaril@544: versa. You can change this default behaviour in the settings menu (see
insilmaril@544: \ref{settings}).
insilmaril@104: 
insilmaril@28: \section{Mapeditor} \label {mapeditor}
insilmaril@28: \subsection{Start a new map}
insilmaril@486: 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
insilmaril@28: will just need the mapeditor. 
insilmaril@28: 
insilmaril@28: Select the mapcenter "New map" in the middle of the mapeditor by
insilmaril@486: left-clicking with the mouse. It will be highlighted yellow to show that is
insilmaril@103: selected. There are several ways to add a new branch to the center:
insilmaril@28: \begin{itemize}
insilmaril@486: 	\item Using the mouse: Open the context menu by clicking with the
insilmaril@103: 	right mouse button (CTRL-Click on Mac) onto the
insilmaril@486: 	mapcenter and choose Add \ra Add branch as child
insilmaril@103: 	\item Press \key{Ins} or \key{A}
insilmaril@28: \end{itemize}
insilmaril@28: A new branch will appear and you will be able to type the heading of the
insilmaril@28: branch. Finish adding the new branch by pressing \key{Enter}.
insilmaril@28: %tipp
insilmaril@486: Sometimes it comes in handy to be able to add a new branch above or below the current
insilmaril@486: one. 
insilmaril@486: \begin{itemize}
insilmaril@509: 	\item Use \key{Shift-A} to add a branch above the selected one or... 
insilmaril@509: 	\item \key{Ctrl-A} to add one below. 
insilmaril@486: \end{itemize}
insilmaril@486: It is also
insilmaril@104: possible to add a branch in such a way, that the current selection
insilmaril@104: becomes the child of the new branch, which is like inserting it {\em
insilmaril@104: before} the selection. This can be done using the context menu.
insilmaril@28: 
insilmaril@509: \hint{To delete a branch press \key{CTRL-X}. If enabled in the Settings
insilmaril@544: menu (see \ref{settings}), you can also use the \key{Del} key.}
insilmaril@509: 
insilmaril@28: \subsection{Navigate through a map}
insilmaril@28: \subsubsection*{Select branches}
insilmaril@28: To select branches you can use the left button of your mouse or also the
insilmaril@486: arrow keys. Depending on the {\em orientation} of a branch tap
insilmaril@486: \key{\la} or \key{\ra} to move nearer to the mapcenter or deeper
insilmaril@28: down into the branches. Within a set of branches, let's call them a 
insilmaril@640: {\em subtree}, you can use \key{PgUp} and \key{PgDn} to go up and down. You can
insilmaril@486: also use \key{Home} and \key{End} to select the first and last branch.
insilmaril@28: 
insilmaril@28: 
insilmaril@486: \subsubsection*{Panning the view of a map}
insilmaril@28: While adding more and more branches the size of the map may become
insilmaril@486: larger than the mapeditor window. You can use the scrollbars on the
insilmaril@486: 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
insilmaril@486: mouse pointer will change from an arrow to a hand, now move or drag the visible
insilmaril@486: map to show the desired part.
insilmaril@28: 
insilmaril@28: If you select branches using the arrow keys, the map will scroll
insilmaril@28: to ensure that the selected branch is always visible.
insilmaril@28: 
insilmaril@486: \subsubsection*{Zooming the view of a map}
insilmaril@28: Working with huge maps, the {\em zoom}-function comes in handy: You can
insilmaril@28: use 
insilmaril@28: \begin{itemize}
insilmaril@486: 	\item from the menu: View \ra Zoom in, View \ra Zoom out, View \ra reset Zoom.
insilmaril@28: 	\item the toolbar buttons 
insilmaril@28: 		\begin{center}
insilmaril@450: 			\includegraphics[width=3cm]{images/zoom-buttons.png}
insilmaril@28: 		\end{center}	
insilmaril@28: \end{itemize}	
insilmaril@486: Clicking the crossed magnifying lens icon will reset the zoomed view to its original size.
insilmaril@28: 
insilmaril@28: 
insilmaril@28: \subsubsection*{Find Function} \label{findwindow}
insilmaril@28: With huge maps there is the need to have a
insilmaril@28: find function. Choose Edit \ra Find to open the Find Window:
insilmaril@28: \begin{center}
insilmaril@450: 	\includegraphics[width=6cm]{images/find-window.png}
insilmaril@28: \end{center}	
insilmaril@486: 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
insilmaril@486: fails, a short message "Nothing found" will appear for a few
insilmaril@28: seconds in the {\em statusbar} on the bottom of the mapeditor.
insilmaril@28: 
insilmaril@260: \subsubsection*{Keep the overview -- scroll a part of the map}
insilmaril@486: A very big subtree of a map e.g. a branch with hundreds of child branches would make
insilmaril@28: it very hard to keep an overview over the whole map. You can hide all
insilmaril@486: 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
insilmaril@486: broadsheet newspaper. You can scroll or fold the paper to a small roll, leaving just
insilmaril@486: the headline visible.
insilmaril@28: 
insilmaril@486: To scroll or unscroll a branch and its children,
insilmaril@28: \begin{itemize}
insilmaril@486: 	\item press either the \key{Scroll Lock} key or the \key{S}
insilmaril@28: 	\item press the middle-mouse button or
insilmaril@486: 	\item choose the scroll icon from the toolbar.
insilmaril@28: \end{itemize}
insilmaril@28: If you select parts of a scrolled branch e.g. using the find function or
insilmaril@28: by using the arrow-keys, it will unscroll temporary. This is shown as a
insilmaril@486: scroll with a little hour glass. If the temporary unscrolled part is no
insilmaril@28: longer needed, it will be hidden again automatically. It is also
insilmaril@486: possible to unscroll all branches using "Edit\ra Unscroll all scrolled
insilmaril@486: branches".
insilmaril@28: 
insilmaril@264: You can also hide parts of the map while exporting it e.g. to a webpage
insilmaril@264: or a presentation, see \ref{hideexport} for details.
insilmaril@28: 
insilmaril@28: \subsection{Modify and move branches}
insilmaril@260: \subsubsection*{Modify the heading}
insilmaril@28: You can edit the heading by selecting the branch and then
insilmaril@28: \begin{itemize}
insilmaril@28: 	\item pressing \key{Enter}
insilmaril@486: 	\item pressing \key{F2}
insilmaril@28: 	\item double-clicking with left mouse.
insilmaril@28: \end{itemize}
insilmaril@28: Just type the new heading (or edit the old one) and press \key{Enter}.
insilmaril@28: 
insilmaril@28: \subsubsection*{Move a branch}
insilmaril@28: The easiest way to move a branch is to select it with left-mouse and
insilmaril@28: drag it to the destination while keeping the mouse button pressed.
insilmaril@28: Depending on the branch  it will be
insilmaril@28: \begin{itemize}
insilmaril@28: 	\item moved to the destination or
insilmaril@28: 	\item {\em linked} to a new {\em parent} (mapcenter or branch)
insilmaril@28: \end{itemize}
insilmaril@28: If you drag the branch over another one or over the mapcenter, you will
insilmaril@28: notice that the  link connecting it to the old parent will be changed to
insilmaril@28: lead to the  new parent which is now under your mousepointer. 
insilmaril@28: If you release the button now, the branch will be relinked.
insilmaril@28: 
insilmaril@28: If you release the button in the middle of nowhere, the result will
insilmaril@28: depend on the type of branch you are releasing:
insilmaril@28: \begin{itemize}
insilmaril@28: 	\item A mainbranch is directly connected to the mapcenter.
insilmaril@28: 		It will stay on its new position.
insilmaril@28: 	\item An ordinary branch will "jump" back to its original position.	
insilmaril@28: \end{itemize}
insilmaril@28: Thus you can easily rearrange the layout of the mainbranches to avoid
insilmaril@28: overlapping of their subtrees.
insilmaril@28: There is another convenient way to move branches, especially if you want
insilmaril@28: to {\em reorder} a subtree: You can move a branch up or down in a
insilmaril@28: subtree by
insilmaril@28: \begin{itemize}
insilmaril@28: 	\item pressing \key{\ua} and \key {\da}
insilmaril@28: 	\item selecting Edit \ra Move branch
insilmaril@28: 	\item clicking on the toolbar buttons:
insilmaril@28: 		\begin{center}
insilmaril@450: 			\includegraphics[width=1.5cm]{images/move-buttons.png}
insilmaril@28: 		\end{center}	
insilmaril@28: \end{itemize}
insilmaril@28: %tipp
insilmaril@28: There is yet another way to move branches: If you press \key{Shift} or
insilmaril@28: \key{Ctrl} while moving with the mouse, the branch will be added above
insilmaril@486: or below the one the mouse pointer is over. This can also be used to reorder branches in a map.
insilmaril@28: 
insilmaril@486: \subsection{Colours and Images - Using the right side of your brain}
insilmaril@486: \subsubsection*{Change colour of a heading}
insilmaril@486: You can also use colours to add more information to a map, e.g. use
insilmaril@486: red, green and more colours to prioritize tasks. Again you can
insilmaril@28: \begin{itemize}
insilmaril@486: 	\item use the menu and choose e.g Format \ra Set Color
insilmaril@28: 	\item use the toolbar
insilmaril@28: 		\begin{center}
insilmaril@493: 			\includegraphics[width=3cm]{images/color-buttons.png}
insilmaril@28: 		\end{center}	
insilmaril@28: \end{itemize}
insilmaril@486: The first button (black in the graphic above) shows the current colour.
insilmaril@486: Clicking on it let's you choose another colour. You can also "pick"
insilmaril@486: another colour by selecting a branch with the desired colour and using the
insilmaril@486: "pick colour" button. Both of the icons showing a palette actually apply
insilmaril@486: the current colour to the selected branch. While the first one just
insilmaril@486: colours the heading of the selection, the last one also colours all the
insilmaril@486: children of the selected branch.
insilmaril@28: 
insilmaril@28: %tipp
insilmaril@486: A very useful function is the "copy colour" using the mouse: Select the
insilmaril@486: branch which should get the new colour, then press \key{Ctrl} and
insilmaril@486: simultanously click with left-mouse on another branch to copy its colour
insilmaril@486: to the first one. Here the children of the selection also will get the new
insilmaril@486: colour, if you just want to colour the selection itself, additionally
insilmaril@28: press \key{Shift}.
insilmaril@28: 
insilmaril@28: \subsubsection*{Use flags}
insilmaril@486: \vym provides various flags. They are usually displayed in the toolbar on top of the
insilmaril@28: mapeditor window. (Note: Like all toolbars you can also move them to the
insilmaril@28: left or the right side of the window or even detach them. Just grab the
insilmaril@28: very left "dotted" part of the toolbar with your left-mouse button.) 
insilmaril@509: 	\maximage{images/default-flags.png}
insilmaril@28: If you have a branch selected, you can set any number of flags by
insilmaril@28: clicking them in the toolbar. The toolbar buttons change their state and
insilmaril@486: 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.
insilmaril@28: 
insilmaril@486: At present \vym uses two kinds of flags: {\em System Flags} and {\em
insilmaril@28: Standard Flags}. The standard flags are those shown in the toolbar.
insilmaril@28: System flags are set by \vym to indicate e.g. that there is additional
insilmaril@28: information in a note (more on this in \ref{noteeditor}). Later versions
insilmaril@28: of \vym may have another kind of flags, which may be edited by the user.
insilmaril@28: 
insilmaril@28: \subsubsection*{Images}
insilmaril@125: The easiest way to add an image to a branch is by dragging it e.g. from a
insilmaril@125: webbrowser to the mapeditor while a branch is selected there.
insilmaril@125: 
insilmaril@486: You can also add an image to a branch by opening the context menu of the
insilmaril@493: branch. Right click the selected branch, choose "Add Image". A
insilmaril@486: dialog window enables you choose the image to load. 
insilmaril@28: \footnote{Supported image types are: PNG, BMP, XBM, XPM and PNM. It may
insilmaril@28: 	also support JPEG, MNG and GIF, if specially configured during
insilmaril@28: 	compilation (as done when \vym is part of SUSE LINUX).}
insilmaril@486: While an image is selected in the dialog, a preview of the
insilmaril@486: image is displayed. It is also possible to select multiple images.	
insilmaril@28: 
insilmaril@28: You can position the image anywhere you want, just drag it with left
insilmaril@28: mouse. To relink it to another branch, press \key{Shift} while moving
insilmaril@28: it. To delete it, press \key{Del}. 
insilmaril@28: 
insilmaril@28: If you right-click onto an image, a context menu will open which let's
insilmaril@28: you first choose one of several image formats. Then a file dialog opens
insilmaril@486: to save the image. 
insilmaril@486: 
insilmaril@486: Hint: This is used to "export" the image, it will be
insilmaril@28: saved anyway in the map itself! You can also cut and
insilmaril@28: copy images, but it is not possible to add objects to an image\footnote{
insilmaril@28: 	Images are regarded as "extra feature". It would make working with
insilmaril@28: 	the map much more complex if e.g. images could be linked to images.}
insilmaril@28: 
insilmaril@28: The option \lq{\bf Use for export} \rq controls the output of exports
insilmaril@28: e.g. to HTML: If set to no, the image won't appear in the {\em text}
insilmaril@28: part of the output. This is useful for large images or if images are
insilmaril@28: used as a kind of frame e.g. the famous cloud symbol around a part of
insilmaril@28: the map. Those shouldn't appear in the middle of the text.
insilmaril@28: 
insilmaril@28: At the moment image support is preliminary: Images will be saved
insilmaril@28: together with all the other data of a map in the {\tt .vym}-file.
insilmaril@28: Later versions will include more functionality like resizing the images,
insilmaril@28: changing its z-value (put it into background) etc.
insilmaril@28: 
insilmaril@28: \subsubsection*{Frames}
insilmaril@493: A frame can be added to a branch in the {\em property window} (see
insilmaril@493: \ref{propwindow}). 
insilmaril@493: Alternatively, you can use use images as frames. Have a look at the demo
insilmaril@493: map {\tt todo.vym} as an example, where the mapcenter is a cloud. You
insilmaril@493: can use an external drawing program like {\tt gimp} to create an image,
insilmaril@28: preferable with an transparency channel, so that you can design frames
insilmaril@493: which don't use a rectangular borderline, just like that cloud.
insilmaril@28: 
insilmaril@28: 
insilmaril@493: \subsection{Design of map background and connecting links }
insilmaril@28: The design of the background of a map and also of the links connecting
insilmaril@28: various parts of the map can be changed by
insilmaril@28: \begin{itemize}
insilmaril@28: 	\item Selecting Format from the menu
insilmaril@486: 	\item Right clicking on the canvas, which will open a context menu
insilmaril@28: \end{itemize}
insilmaril@28: 
insilmaril@493: \subsubsection*{Background }
insilmaril@486: The colour is set (and also displayed) as "Set background colour".
insilmaril@493: Alternatevily you can set an background image, though this is not
insilmaril@493: recommended in general. Working on the map becomes slow and the image
insilmaril@493: currently cannot be positioned freely.
insilmaril@28: 
insilmaril@486: \subsubsection*{Link colour}
insilmaril@486: Links connecting branches can be coloured in one of two ways:
insilmaril@28: \begin{itemize}
insilmaril@486: 	\item use the same colour for the heading and for the branch link line.
insilmaril@486: 	\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.
insilmaril@28: \end{itemize}
insilmaril@486: The latter can be set with "Set link colour". Check or uncheck the "Use
insilmaril@486: colour of heading for link" option to toggle between the two designs for
insilmaril@28: your map.
insilmaril@28: 
insilmaril@28: \subsubsection*{Link style}
insilmaril@28: \vym offers four different styles for the appearences of links:
insilmaril@28: \begin{itemize}
insilmaril@28: 	\item Line
insilmaril@28: 	\item Parabel
insilmaril@28: 	\item Thick Line
insilmaril@28: 	\item Thick Parabel
insilmaril@28: \end{itemize}
insilmaril@486: The "thick" styles only apply to links starting at the mapcenter, link lines for the rest
insilmaril@486: of the map are always painted "thin".
insilmaril@28: 
insilmaril@28: 
insilmaril@260: \subsection{Links to other documents and webpages}
insilmaril@260: \vym supports two kind of external links:
insilmaril@28: \begin{itemize}
insilmaril@28: 	\item Document, which will be opened in an external webbrowser
insilmaril@28: 	\item \vym map, which will be opened in \vym itself
insilmaril@28: \end{itemize}
insilmaril@260: In addition to the external links there also internal ones, leading from one
insilmaril@486: branch in a map to another one. Those are called {\em XLinks} and are explained
insilmaril@260: in section~\ref{xlinks}.
insilmaril@28: 
insilmaril@28: \subsubsection*{Webbrowser}
insilmaril@486: Modern Webbrowsers like {\tt konqueror and Firefox} are able to display various
insilmaril@486: types of files, both local or on the internet. To enter the URL of
insilmaril@528: any document, press \key{U} or right-click  onto a branch to open the contextmenu then choose
insilmaril@528: "References\ra Edit URL". If you want to use a file dialog to
insilmaril@602: conveniently choose a local file you can use~\key{U}.
insilmaril@528: 
insilmaril@528: After an URL was entered, a little globe will appear in the branch. By
insilmaril@28: clicking on the globe in the toolbar or the context menu an external
insilmaril@28: browser\footnote{
insilmaril@544: 	The browser can be changed in the Settings Menu (see \ref{settings}).}
insilmaril@486: will be launched.
insilmaril@28: \begin{center}
insilmaril@450: 	\includegraphics[width=0.5cm]{images/flag-url.png}
insilmaril@28: \end{center}
insilmaril@340: For more information on working with bookmarks and webbrowsers see
insilmaril@340: section \ref{bookmarks}.
insilmaril@266: 
insilmaril@493: In the context menu there is also an option to open all URLs found
insilmaril@493: in the selected subtree of the map. That's useful to simultanously open
insilmaril@493: a collection of URLs in the webbrowser, especially if the browser can
insilmaril@493: open them in tabs (like Konqueror).
insilmaril@493: 
insilmaril@28: 
insilmaril@28: \subsubsection*{\vym map}
insilmaril@486: 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
insilmaril@28: branch with a link is marked with 
insilmaril@28: \begin{center}
insilmaril@450: 	\includegraphics[width=0.5cm]{images/flag-vymlink.png}
insilmaril@28: \end{center}
insilmaril@486: 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
insilmaril@486: multiple maps). To delete an existing link, just right click the branch and select "Delete \vym link".
insilmaril@28: 
insilmaril@493: In the context menu there is also an option to open all vymlinks found
insilmaril@493: in the selected subtree of the map. That's useful to simultanously open
insilmaril@493: a collection of related maps.
insilmaril@493: 
insilmaril@28: Technical note: Internally \vym uses absolute paths, to avoid opening
insilmaril@28: several tabs containing the same map. When a map is saved, this path is
insilmaril@28: converted to a relative one (e.g. {\tt /home/user/vym.map} might become
insilmaril@28: {\tt ./vym.map}. This makes it fairly easy to use multiple maps on
insilmaril@28: different computers or export them to HTML in future.
insilmaril@28: 
insilmaril@28: \subsection{Multiple maps} \label{tabs}
insilmaril@28: You can work on multiple maps at the same time. Each new map is opened
insilmaril@28: in another {\em tab}. The available tabs are shown just above the
insilmaril@28: mapeditor. You can use the normal cut/copy/paste functions to
insilmaril@28: copy data from one map to another.
insilmaril@28: 
insilmaril@28: %todo
insilmaril@28: 
insilmaril@28: %TODO
insilmaril@28: %\subsubsection{Menus}
insilmaril@28: %\subsubsection{Keyboard shortcuts}
insilmaril@28: 
insilmaril@28: % Settings
insilmaril@28: % Images
insilmaril@28: % Copy & Paste
insilmaril@28: % Working with tabs (multiple maps)
insilmaril@28: % Exporting
insilmaril@28: % Scrolling
insilmaril@28: 
insilmaril@28: \section{Noteeditor} \label {noteeditor}
insilmaril@486: If you want to attach more text to a branch e.g. a complete email, a
insilmaril@28: cooking recipe, or the whole source code of a software project, you can
insilmaril@125: use the noteeditor. 
insilmaril@509: 	\maximage{images/noteeditor.png}
insilmaril@486: This editor displays text associated with a branch selected in the mapeditor. The noteeditor
insilmaril@486: shows different background colours depending on whether text is associated with a selected branch.
insilmaril@28: 
insilmaril@125: \subsection{States}
insilmaril@28: Before you can type or paste text into it, you have
insilmaril@486: to select a branch in the mapeditor. Note that the background colour
insilmaril@28: of the noteeditor indicates its state:
insilmaril@28: \begin{itemize}
insilmaril@28: 	\item grey: no text entered yet
insilmaril@486: 	\item white: some text has been entered
insilmaril@28: \end{itemize}	
insilmaril@486: In the mapeditor itself, to signal that there is a note with more
insilmaril@486: information for a particular branch, a little "note" flag will appear next
insilmaril@486: to the heading of the branch. This is illustrated in the lower branch on the right hand side:
insilmaril@509: 	\maximage{images/branches-flags.png}
insilmaril@28: 
insilmaril@125: \subsection{Import and export notes}
insilmaril@420: The note is always saved automatically within the \vym map itself.
insilmaril@28: Nevertheless sometimes it is nice to import a note from an external file
insilmaril@486: or write it. In the Note Editor use "File\ra~Import" and "File\ra~Export" to do so. 
insilmaril@28: 
insilmaril@125: \subsection{Edit and print note}
insilmaril@28: Editing works like in any simple texteditor, including undo and redo
insilmaril@28: functions. You can delete the complete note by clicking the
insilmaril@28: trashcan. Only the note itself is printed by clicking the printer icon.
insilmaril@28: 
insilmaril@486: \subsection{RichText: Colours, paragraphs and formatted text}
insilmaril@233: \vym supports formatted text (QT Rich Text) in the noteeditor since
insilmaril@486: version 1.4.7.  Colours and text attributes (e.g. italic, bold) can be
insilmaril@486: set with the buttons above the text.  The text itself is divided into
insilmaril@233: paragraphs. For each paragraph the format can be set (e.g. centered,
insilmaril@233: right). A paragraph is ended when a \key{Return} is entered. If you just
insilmaril@233: want to begin a new line, press \key{CTRL-Return}.
insilmaril@233: 
insilmaril@486: \subsection{Fonts and how to switch them quickly}
insilmaril@486: The noteeditor is designed to be used for simple notes, not really as a full
insilmaril@493: featured word processor. Because of many requests \vym supports 
insilmaril@28: formatted text in the noteeditor\footnote{
insilmaril@28: 	\vym uses the QRichtText format, which is basically a subset of the
insilmaril@28: 	formatting provided in HTML.}
insilmaril@544: Two default fonts are supported which can be set in the Settings menu
insilmaril@544: (see \ref{settings}).
insilmaril@28: One is a fixed width font, the other has variable width. The fixed font
insilmaril@28: is usually used for emails, source code etc.\ while the variable font is
insilmaril@28: used for simple notes, where one doesn't need fixed character widths.
insilmaril@28: Both fonts can easily switched using the following symbol from the
insilmaril@28: toolbar:
insilmaril@28: \begin{center}
insilmaril@450: 	\includegraphics[width=0.5cm]{images/formatfixedfont.png}
insilmaril@28: \end{center}
insilmaril@486: 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.
insilmaril@28: 
insilmaril@28: Additionally to the default fonts any font installed on your system can
insilmaril@28: be used. Please note, that the chosen font also will be used for HTML
insilmaril@486: 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.
insilmaril@28: 
insilmaril@217: \subsection{Find text}
insilmaril@28: The noteeditor itself has no Find function, use Find in the mapeditor,
insilmaril@28: which will also search all notes (see \ref{findwindow}).
insilmaril@28: 
insilmaril@217: \subsection{Paste text into note editor}
insilmaril@28: Often you will paste text into the editor from another application e.g.
insilmaril@28: an email. Normally \vym will generate a new paragraph for each new line.
insilmaril@28: This usually is not what you want, so you can choose from the menu
insilmaril@28: 
insilmaril@493: 
insilmaril@28: \section{Hello world}
insilmaril@233: This section is about how \vym can interact with other applications.
insilmaril@486: Many applications can now read and write their data using XML, the
insilmaril@233: eXtensible Markup Language. \vym also uses XML to save its maps, see
insilmaril@233: \ref{fileformat} for a more detailed description. 
insilmaril@233: 
insilmaril@486: So if you make use of another application that understands XML, chances are good that someone
insilmaril@233: could write import/export filters for \vym. Volunteers are always
insilmaril@233: welcome ;-)
insilmaril@233: 
insilmaril@340: \subsection{Import} \label{import}
insilmaril@233: 
insilmaril@233: \subsubsection*{KDE Bookmarks}
insilmaril@486: The integrated bookmark editor in KDE (Konqueror etc.) is somewhat limited, so why not
insilmaril@233: use \vym to maintain the bookmark mess? To create a new map containing
insilmaril@233: your current KDE bookmarks just choose
insilmaril@233: \begin{itemize}
insilmaril@486: 	\item File \ra Import\ra KDE Bookmarks
insilmaril@233: \end{itemize}
insilmaril@233: 
insilmaril@233: \subsubsection*{Mind Manager}
insilmaril@233: \vym has currently a very basic import filter to convert maps created by
insilmaril@486: {\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
insilmaril@486: \href{http://mindjet.com}{http://mindjet.com}} into \vym maps. Notes and
insilmaril@233: pictures are not converted at the moment. You can import files with
insilmaril@233: \begin{itemize}
insilmaril@486: 	\item File \ra Import\ra Mind Manager
insilmaril@233: \end{itemize}
insilmaril@233: 
insilmaril@233: 
insilmaril@233: \subsubsection*{Directory structure}
insilmaril@233: \vym can read a directory structure. This is mainly for
insilmaril@233: testing \vym e.g. to easily create huge maps used for benchmarks (yes,
insilmaril@233: there is still room to optimize \vym ;-)
insilmaril@28: 
insilmaril@340: 
insilmaril@340: 
insilmaril@340: 
insilmaril@340: \subsection{Export}  \label{export}
insilmaril@264: \label{hideexport}
insilmaril@486: Often you may not want to export the whole map, but just parts of it. For
insilmaril@264: example you may have additional info you want to talk about in a
insilmaril@264: presentation, while those parts should not be visible to the audience.
insilmaril@264: To achieve this you can "hide" parts of the map during exports by
insilmaril@291: setting the "hide in export" flag.
insilmaril@264: \begin{center}
insilmaril@450: 	\includegraphics[width=0.5cm]{images/flag-hideexport.png}
insilmaril@264: \end{center}
insilmaril@291: You can toggle this flag in the toolbar or by pressing \key{H}.
insilmaril@544: Note that there is a global option in the settings menu (
insilmaril@544: \ref{settings}) to toggle the use of this flag. By default the flag is
insilmaril@544: enabled.
insilmaril@233: 
insilmaril@233: \subsubsection*{Open Office}
insilmaril@486: Open Office beginning with version~2 uses the so called "Open Document Format", which can be written by \vym. The options are
insilmaril@233: currently limited, but it possible to export presentations which can be
insilmaril@233: opened in Open Office Impress. By selecting
insilmaril@28: \begin{itemize}
insilmaril@486: 	\item File  \ra Export\ra Open Office
insilmaril@28: \end{itemize}
insilmaril@233: you get a file dialogue where you can choose the output file and the
insilmaril@233: file type:
insilmaril@509: 	\maximage{images/export-oo.png}
insilmaril@233: The file types represent various templates, which can be created with
insilmaril@233: some manual work from an existing Open Office document. The structure of
insilmaril@233: \vym map is then inserted into a template. 
insilmaril@233: There are some limitations at the moment:
insilmaril@233: \begin{itemize}
insilmaril@233: 	\item \vym can't take care of page lengths, so you have to check and
insilmaril@233: 	probably reedit in Open Office to avoid text running over the end of
insilmaril@233: 	a page
insilmaril@233: 	\item Images and flags are not used at the moment
insilmaril@486: 	\item Notes are just written as plain text, without RichText 
insilmaril@486: 	\item The full range of templates are not available in all distributions.	
insilmaril@233: \end{itemize}
insilmaril@486: Some of the templates make use of {\em sections} i.e sections insert the
insilmaril@233: headings of mainbranches as chapters for sections into the presentation.
insilmaril@28: 
insilmaril@28: \subsubsection*{Image}
insilmaril@28: \vym supports all image formats which are natively supported by the
insilmaril@28: QT~toolkit:
insilmaril@28: BMP, JPEG, PBM, PGM, PNG, PPN, XPM, and XBM.
insilmaril@28: For use in websites and for sending images by email PNG is a good
insilmaril@28: recommodation regarding quality and size of the image. \vym uses QTs
insilmaril@28: default options for compressing the images.
insilmaril@28: 
insilmaril@28: \subsubsection*{ASCII}
insilmaril@28: Exporting an image as text is somewhat experimental at the moment. Later
insilmaril@486: this will probably be done using stylesheets. So the output may change in
insilmaril@28: future versions of \vym.
insilmaril@28: 
insilmaril@233: \subsubsection*{\LaTeX}
insilmaril@233: \vym can generate an input file for \LaTeX. Currently this is considered
insilmaril@233: as experimental, there are no options (yet). 
insilmaril@233: By selecting
insilmaril@233: \begin{itemize}
insilmaril@486: 	\item File  \ra Export\ra \LaTeX 
insilmaril@233: \end{itemize}
insilmaril@233: you will be asked in a file dialog for the name of the output file. This
insilmaril@486: file may then be included in a \LaTeX document using command: 
insilmaril@233: \begin{verbatim}
insilmaril@233: 	\include{inputfile.tex}
insilmaril@233: \end{verbatim}
insilmaril@233: 
insilmaril@340: \subsubsection*{KDE Bookmarks}
insilmaril@340: \vym will overwrite the KDE bookmarks file and then try to notify
insilmaril@486: running Konquerors via DCOP of the changed file. \vym does not create a
insilmaril@340: backup!
insilmaril@340: \begin{itemize}
insilmaril@486: 	\item File \ra Export \ra KDE Bookmarks
insilmaril@340: \end{itemize}
insilmaril@340: 
insilmaril@340: 
insilmaril@233: \subsubsection*{XHTML (Webpages)}
insilmaril@233: 
insilmaril@486: This is the format to use if you wish to create a webpage. To see an example
insilmaril@486: visit the \vym homepage: 
insilmaril@233: \href{http://www.InSilmaril.de/vym}{www.InSilmaril.de/vym}
insilmaril@233: 
insilmaril@486: Some explanation on how this works: 
insilmaril@233: Before a map is exported as XHTML, it will be first written as XML into a
insilmaril@28: directory (see \ref{xmlexport}). Then the external program {\tt
insilmaril@486: xsltproc}\footnote{On SUSE Linux and some other distributions {\tt xsltproc} is installed by
insilmaril@28: default.}
insilmaril@28: will be called to process the XML file and generate HTML code.
insilmaril@486: A dialog allows the user to set various options:
insilmaril@28: \begin{itemize}
insilmaril@28: 	\item {\bf Include image:} If set, \vym will creat an image map at
insilmaril@28: 	the top of the HTML output. Clicking on a branch in the map will
insilmaril@28: 	jump to the corresponding section in the output.
insilmaril@28: 
insilmaril@28: 	\item {\bf Colored headings:}
insilmaril@486: 	If set to yes, \vym will colour the headings in the text part  with the
insilmaril@486: 	same colours used in the \vym map.
insilmaril@28: 	\item {\bf Show Warnings:}
insilmaril@28: 	If set to yes, \vym will ask before overwriting data.
insilmaril@28: 	\item {\bf Show output:}
insilmaril@28: 	This is useful mainly for debugging. It will show how the processing of
insilmaril@28: 	the XML file works by calling the external {\tt xsltproc}.
insilmaril@28: \end{itemize}
insilmaril@28: Additionally the paths to the CSS and XSL stylesheets can be set. By
insilmaril@28: default on SUSE~Linux they will be in {\tt /usr/share/vym/styles}.
insilmaril@28: 
insilmaril@28: 
insilmaril@28: \subsubsection*{XML} \label{xmlexport}
insilmaril@486: The map is written into a directory both as an image and as an XML file. The
insilmaril@28: directory is set in a file dialog. If the directory is not empty, you
insilmaril@486: will be warned and offered choices if you are at risk of overwriting existing contents.
insilmaril@28: 
insilmaril@28: It is possible to export different maps into the same directory. Each
insilmaril@28: file generated will have the map's name as prefix, e.g. {\tt todo.vym}
insilmaril@28: becomes {\tt todo.xml}, {\tt todo.png}, {\tt todo-image-1.png} and so
insilmaril@486: on. This is useful if, for example, a website comprises several combined maps that have to be stored in the same directory.
insilmaril@28: 
insilmaril@105: \subsubsection*{Export a part of a map}
insilmaril@486: Select a branch you want to export together with its children, then open
insilmaril@105: the context menu and choose {\em Save Selection}. This will create a
insilmaril@486: file with the suffix {\tt .vyp}, which is an abbreviation for \lq vym
insilmaril@105: part\rq.
insilmaril@105: 
insilmaril@125: 
insilmaril@125: \section{Advanced Editing}
insilmaril@340: 
insilmaril@493: \subsection{Properties of an object} 
insilmaril@493: For any branch you can open a satellite window (see \ref{satellite}):
insilmaril@493: the {\em property window}:
insilmaril@493: \begin{center}
insilmaril@493: 	\includegraphics[width=8cm]{images/propwindow.png}
insilmaril@493: 	\label{propwindow}
insilmaril@493: \end{center}
insilmaril@493: %FIXME create screenshot
insilmaril@493: %FIXME explain the tabs
insilmaril@493: 
insilmaril@493: \begin{itemize}
insilmaril@493: 	\item Frame
insilmaril@493: 	\item Link (see \ref{hideunselected})
insilmaril@493: 	\item Layout (see \ref{incimg})
insilmaril@493: \end{itemize}
insilmaril@493: 
insilmaril@420: \subsection{Changing the history: Undo and Redo}
insilmaril@493: \vym keeps track of all changes done in a map. The default number of
insilmaril@493: changes which can be undone is~75. The complete history can be seen in
insilmaril@493: the {\em historywindow}:
insilmaril@509: 	\maximage{images/historywindow.png}
insilmaril@493: 	\label{historywindow}
insilmaril@493: A single step back be undone or redone with \key{CTRL-Z} or \key{CTRL-Y},
insilmaril@493: or by using the buttons in the toolbar or the {\em historywindow}.
insilmaril@493: Inside the {\em historywindow}, you can click on a line to unwind all
insilmaril@493: actions done until that point in time -- or redo all changes by clicking
insilmaril@493: on the last line.
insilmaril@420: 
insilmaril@509: \hint{
insilmaril@509: 	You can "paste from the past": Go back in time by e.g. with
insilmaril@509: 	\key{CTRL-Z}, then copy to clipboard by pressing \key{CTRL-C}.
insilmaril@509: 
insilmaril@509: 	Now do all actions again, e.g. by \key{CTRL-Y} or clicking on the
insilmaril@509: 	last action in {\em historywindow}. Now paste from the past with
insilmaril@509: 	\key{CTRL-V}.
insilmaril@509: }
insilmaril@509: 
insilmaril@450: \subsection{Macros} \label{macros}
insilmaril@527: Macros have been added to \vym in version~1.9.0. 
insilmaril@527: So far they have a preliminary character, maybe they are going to be
insilmaril@527: replaced by full-featured scripting functionality later (though the
insilmaril@527: commands will be more or less the same).
insilmaril@527: 
insilmaril@527: Each function key
insilmaril@450: \key{F1} to \key{F12} holds a macro, which is executed on the current
insilmaril@486: selection if the key is pressed. The default macros change the colour of
insilmaril@450: a subtree or set the frame of a branch:
insilmaril@450: \begin{center}
insilmaril@450: 	\includegraphics[width=8cm]{images/macros.png}
insilmaril@450: \end{center}
insilmaril@450: Each macro is a \vym script, which is executed when the associated key
insilmaril@450: is pressed. The default location of the scripts can be changed in the
insilmaril@450: Settings menu. More information on using scripts in \vym is found in
insilmaril@544: [\ref{settings})
insilmaril@450: appendix~\ref{scripts}.
insilmaril@450: 
insilmaril@493: \subsection{Bookmarks} \label{bookmarks}
insilmaril@340: \subsubsection*{Open new tabs instead of new windows}
insilmaril@486: If you use konqueror as your browser, \vym will remember the konqueror session which
insilmaril@340: was opened first by \vym. You can also press \key{Ctrl} and click to
insilmaril@486: open the link in a new tab.
insilmaril@340: 
insilmaril@340: \vym can also open a new tab in Mozilla or Firefox using the remote
insilmaril@340: command\footnote{\href{http://www.mozilla.org/unix/remote.html}{http://www.mozilla.org/unix/remote.html}}
insilmaril@486: of these browsers.
insilmaril@340: 
insilmaril@340: \subsubsection*{Drag and Drop}
insilmaril@340: If you want to keep bookmarks in a map, select a branch where you want
insilmaril@340: to add the bookmark, then simply drag the URL from your browser to the
insilmaril@340: map. Also you could use an existing heading as URL: Right click onto the
insilmaril@340: branch and select "Use heading for URL".
insilmaril@340: 
insilmaril@340: 
insilmaril@340: \subsubsection*{Directly access bookmark lists of a browser}
insilmaril@340: Please see the sections \ref{import} and \ref{export} about
insilmaril@340: Import and Export filters.
insilmaril@340: 
insilmaril@340: \subsubsection*{Special URLs}
insilmaril@340: \vym can turn an existing heading of a branch into an URL. Currently
insilmaril@340: this works for Bugentries in the Novell Bugtracking system: Open the
insilmaril@340: context menu of a branch (usually by right-clicking it) and select
insilmaril@340: \begin{itemize}
insilmaril@340: 	\item Create URL to Bugzilla
insilmaril@340: \end{itemize}
insilmaril@340: The URL will be build from the number in the heading.
insilmaril@340: 
insilmaril@493: \subsection{Associating images with a branch} \label{incimg}
insilmaril@486: The default setting for an image is for it to float "freely". Images can be
insilmaril@486: positioned anywhere on the canvas, but may end up in the same place as other
insilmaril@486: parts of the map obscuring that part of the map.
insilmaril@340: 
insilmaril@486: The solution is to insert or include them "into" a branch. This can be done via
insilmaril@493: the property window (see \ref{propwindow}):
insilmaril@340: \begin{itemize}
insilmaril@340: 	\item Include images horizontally
insilmaril@340: 	\item Include images vertically
insilmaril@340: \end{itemize}
insilmaril@486: The image is still positioned relative to its parent branch, but the
insilmaril@486: heading and border of the branch frame adapt to the floating image, see below: 
insilmaril@509: 	\maximage{images/includeImages.png}
insilmaril@340: 
insilmaril@125: \subsection{Modifier Modes} 
insilmaril@486: Modifiers are for example the \key{Shift}- the \key{Ctrl}- ot the \key{Alt}-keys. When
insilmaril@486: pressed while applying mouse actions, they will cause \vym to use
insilmaril@493: a "modified" version of the action which usually would be done. 
insilmaril@493: 
insilmaril@493: %\key{Ctrl} or \key{Alt}is pressed while releasing the branch, it will be
insilmaril@493: %added above/below the target, not as child of the target.
insilmaril@125: 
insilmaril@486: Without a modifier key pressed, the first mouse click on a branch just selects
insilmaril@125: it. For the behaviour of the \key{Ctrl} modifier there are several
insilmaril@125: options, which can be set from the modifier toolbar:
insilmaril@125: \begin{center}
insilmaril@450: 	\includegraphics[width=3cm]{images/modmodes.png}
insilmaril@125: \end{center}
insilmaril@493: The default mode is to copy the colour from the clicked branch to the already
insilmaril@493: selected branch. The figure above shows the toolbar with the default modifier 
insilmaril@493: selected. The second modifier
insilmaril@125: let's you easily copy a whole branch with a single click. The third
insilmaril@493: modifier lets you create links between branches called {\em xLinks}.
insilmaril@493: They will be explained in the next section \ref{xlinks}.
insilmaril@125: 
insilmaril@493: \subsection{Hide links of unselected objects} \label{hidelink}
insilmaril@264: Sometimes it would be useful to position a branch freely, just like a
insilmaril@486: mainbranch or an image. This is possible for all
insilmaril@264: branches, you can use a mainbranch and hide its connecting link to the
insilmaril@486: 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
insilmaril@264: pointing to other maps:
insilmaril@264: \begin{center}
insilmaril@450: 	\includegraphics[width=9cm]{images/hiddenlink.png}
insilmaril@264: \end{center}
insilmaril@493: To hide the link between a branch and its parent open the
insilmaril@493: \ref{propwindow} and check "Hide link if object is not selected" on
insilmaril@493: "Link" tab.
insilmaril@264: 
insilmaril@264: 
insilmaril@260: \subsection{XLinks} \label{xlinks}
insilmaril@125: So far all the data in the \vym map has been treelike. Using xLinks you
insilmaril@125: can link one branch to any other, just like attaching a rope between two
insilmaril@125: branches in a real tree. This is especially useful in complex maps,
insilmaril@486: where you want to have crossreferences which can not be displayed on the same
insilmaril@486: 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:
insilmaril@509: 	\maximage{images/xlink.png}
insilmaril@125: Note that a xLink which points to a branch that is not visible (because
insilmaril@486: it is scrolled), is just shown as a little horizontal arrow. In the
insilmaril@125: screenshot above have a look at the \lq Tuesday\rq\ branch.
insilmaril@125: 
insilmaril@233: \subsubsection*{Create a xLink}
insilmaril@486: Choose the link mode from the modifier toolbar (by clicking the toolbar icon or pressing
insilmaril@125: \key{L}). Select the branch, where the xLink should start. Press the
insilmaril@486: modifier key \key{Ctrl} and then click on the selected branch where the
insilmaril@486: 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.
insilmaril@125: 
insilmaril@233: \subsubsection*{Modify or delete a xLink}
insilmaril@493: First select a branch at either end of the xLink. Then open the context
insilmaril@493: menu and select \lq Edit xLink\rq. A submenu contains all the xLinks of
insilmaril@493: the branch (if there are any). They are named like the branches, where
insilmaril@493: they end. Choose one and the xLink dialogue opens, where you can set
insilmaril@493: colour, width and also delete the xLink.
insilmaril@125: 
insilmaril@233: \subsubsection*{Follow a xLink}
insilmaril@486: In a complex \vym map it sometimes comes in handy to be able to jump to the other end
insilmaril@493: of a xLink. You can do this by opening the context menu of the branch
insilmaril@493: and clicking on \lq Goto xLink\rq and selecting the xLink you want to
insilmaril@493: follow.
insilmaril@125: 
insilmaril@125: 
insilmaril@125: 
insilmaril@233: \subsection{Adding and removing branches}
insilmaril@125: The context menu of a branch shows some more ways to add and delete data
insilmaril@486: e.g. you can delete a branch while keeping its children. The children become
insilmaril@125: linked to the parent of the previously removed branch.
insilmaril@125: Similar branches can be inserted into existing maps. For keyboard
insilmaril@125: shortcuts also have a look at the context menu.
insilmaril@28: 
insilmaril@233: \subsection{Adding a whole map or a part of a map}
insilmaril@493: Select a branch where you want to add a previously saved map ({\tt
insilmaril@493: .vym})or a part of a map ({\tt .vyp}) , then open the context menu and
insilmaril@493: choose {\em Add \ra Add Map (Insert)}. For the import you can choose
insilmaril@493: between {\em Add Map (Insert)} and {\em Add Map (Replace)}: The imported
insilmaril@493: data will be added after the selected branch.
insilmaril@105: 
insilmaril@544: 
insilmaril@105: \section{\vym on Mac OS X}
insilmaril@105: \subsection{Overview}
insilmaril@105: Basically there are two ways to run \vym on Macs:
insilmaril@544: \subsubsection*{Qt Mac Edition:}
insilmaril@105: 	\vym here provides the well known Mac look and feel.  \vym is
insilmaril@544: 	available as Mac OS X application package in contained in a disk
insilmaril@544: 	image ({\tt vym.dmg}. It has been compiled and tested in
insilmaril@544: 	Mac~OS~10.4.  This package includes  runtime libraries of Qt by
insilmaril@544: 	Trolltech.
insilmaril@544: 	
insilmaril@544: \subsubsection*{X11 version} \vym can also be run using the Linux
insilmaril@544: version, but then menus and handling will also be those of the Linux
insilmaril@544: version e.g. The menu bar will look different. 
insilmaril@105: 
insilmaril@125: \subsection	{Contextmenu and special keys}
insilmaril@125: Most Macs unfortunatly just have a single mouse button. In order to show
insilmaril@125: the context menu which usually would be opened with the right mouse
insilmaril@640: button, you can click while pressing the \key{kommand}-key.
insilmaril@125: 
insilmaril@125: Especially on Laptops some of the keys usually used on PC keyboards seem
insilmaril@125: to be missing. The QT-Mac Edition of \vym has its own keyboard
insilmaril@125: shortcuts. To find the shortcuts just have a look at all the menu
insilmaril@125: entries, the shortcut is visible next to an entry. Toolbar buttons also
insilmaril@125: may have shortcuts, just position the mouse pointer over a button and
insilmaril@125: wait for the little help window to appear. 
insilmaril@125: 
insilmaril@125: \subsection {Viewing external links}
insilmaril@125: \vym on Mac uses the system call {\tt /usr/bin/open} to view links.
insilmaril@125: Mac~OS determines automatically if the link is a pdf or www page and
insilmaril@125: opens the right browser.
insilmaril@125: 
insilmaril@233: 
insilmaril@544: \newpage
insilmaril@544: 
insilmaril@233: \begin{appendix}
insilmaril@233: 
insilmaril@486: \section{\vym initialisation process and configuration}
insilmaril@544: \subsection {Settings menu}
insilmaril@544: 	The {\em Settings} menu allows to configure \vym to your needs:
insilmaril@544: 
insilmaril@544: \subsubsection*{Set application to open PDF files} Choose a PDF
insilmaril@544: 	viewer like {\tt acrobat} or {\tt konqueror} which is installed on
insilmaril@544: 	your system.
insilmaril@544: 
insilmaril@544: \subsubsection*{Set application to open external links}
insilmaril@544: 	Choose your favourite webbrowser here.
insilmaril@544: 
insilmaril@544: \subsubsection*{Set path for macros}
insilmaril@544: 	Set the default search path for macros, which will be executed when
insilmaril@544: 	you press one of the function keys. Each key corresponds to a file
insilmaril@544: 	({\tt macro-1.vys..macro12.vys}) in the search path.
insilmaril@544: 
insilmaril@544: \subsubsection*{Set number of undo levels}
insilmaril@544: 	Sets the number of undo/redo levels. The default setting is
insilmaril@544: 	75~levels.
insilmaril@544: 
insilmaril@544: \subsubsection*{Autosave and autosave time}
insilmaril@544: 	Automatic saving of modified maps can be toggled on or off. The
insilmaril@544: 	autosave time is entered in seconds.
insilmaril@544: 
insilmaril@544: \subsubsection*{Edit branch after adding it}
insilmaril@544: 	If set, the heading of a new branch will be edited immediatly after
insilmaril@544: 	adding the branch.
insilmaril@544: 
insilmaril@544: \subsubsection*{Select branch after adding it}
insilmaril@544: 	If set, a new branch will be selected immediatly after adding it.
insilmaril@544: 	When you "brainstorm" on a given keyword, you don't want to go
insilmaril@544: 	deeper and deeper into details, but keep the focus on the keyword.
insilmaril@544: 	So the default setting here is to {\em not} select the freshly added
insilmaril@544: 	branch.
insilmaril@544: 	
insilmaril@544: \subsubsection*{Select existing heading}
insilmaril@544: 	If set and you begin to edit the heading of a branch, the heading text in
insilmaril@544: 	the dialog will be selected. Usefully to copy\&paste to other
insilmaril@544: 	applications.
insilmaril@544: 
insilmaril@544: \subsubsection*{Delete key}
insilmaril@544: 	If set, the \key{Delete} is enabled to, well, delete objects. This
insilmaril@544: 	can be switched off to avoid confusing with the nearby
insilmaril@544: 	\key{Insert}-key on PC keyboards.
insilmaril@544: 
insilmaril@544: \subsubsection*{Exclusive flags}
insilmaril@544: 	If set, some of the standard flags can only be used exclusively,
insilmaril@544: 	e.g.~the smileys.
insilmaril@544: 
insilmaril@544: \subsubsection*{Use hide flags}
insilmaril@544: 	If set, every branch which also has the hide flag set (see
insilmaril@544: 	\ref{hideexport}) will be hidden in exports.
insilmaril@420: \subsection{Configuration file}
insilmaril@420: On startup \vym will look for a configuration for user specific settings
insilmaril@420: like window positions, toolbars etc. If this file does not already
insilmaril@420: exist, it will be created. The file is located in the users home
insilmaril@420: directory. The exact position depends on the platform:
insilmaril@420: \begin{center}
insilmaril@420: \begin{tabular}{cl}
insilmaril@420: 	{\bf Platform}	& {\bf Configuration file} \\ \hline
insilmaril@420: 	Linux		& {\tt $\sim$/.config/InSilmaril/vym.conf  } \\
insilmaril@420: 	Mac OS X	& {\tt /Users/NAME/Library/Preferences/com.insilmaril.vym.plist  } \\
insilmaril@420: \end{tabular}
insilmaril@420: \end{center}
insilmaril@420: The file can be edited manually, or on Mac~OS~X with Property List
insilmaril@420: Editor (installed with xtools).
insilmaril@420: 
insilmaril@291: \subsection{Path to ressources}
insilmaril@291: \vym will try to find its ressources (images, stylesheets, filters,
insilmaril@291: etc.) in the following places:
insilmaril@291: \begin{enumerate}
insilmaril@291: 	\item Path given by the environment variable {\tt VYMHOME}.
insilmaril@291: 	\item If called with the local option (see \ref{options} below),
insilmaril@291: 	      \vym will look for its data in the current directory.
insilmaril@291: 	\item {\tt /usr/share/vym}
insilmaril@291: 	\item {\tt /usr/local/share/vym}
insilmaril@291: \end{enumerate}
insilmaril@291: 
insilmaril@291: \subsection{Command line options} \label{options}
insilmaril@264: \vym has the following options:
insilmaril@264: \begin{center}
insilmaril@450: \begin{tabular}{cccp{8cm}}\\ 
insilmaril@450: \bf Option	& \bf Comment & \bf Argument & \bf Description \\ \hline
insilmaril@493: v & version &			& Show version and codename of \vym\\
insilmaril@450: l & local	&			& Use local paths to stylesheets, translations, icons, 
insilmaril@450:                           etc. instead of system paths. Useful for testing\\
insilmaril@486: h & help	&			& Show help\\
insilmaril@519: r & run 	& filename	& Load and run script\\
insilmaril@479: q & quit	&			& Quit immediatly after startup. Useful for benchmarks.\\
insilmaril@264: \end{tabular}
insilmaril@264: \end{center}
insilmaril@264: You can also give several filenames at the commandline to let \vym open
insilmaril@264: several maps at once.
insilmaril@264:  
insilmaril@450: 
insilmaril@514: \section{Scripts} \label{scripts}   %FIXME
insilmaril@450: 
insilmaril@514: TODO: This section of the \vym manual is not complete yet, sorry.
insilmaril@450: 
insilmaril@514: \subsection{Example scripts}
insilmaril@514: \subsubsection{Export a set of maps}
insilmaril@514: \begin{code}
insilmaril@514: \# Simple vym script to export images of various maps simultanously
insilmaril@519: exportImage ();
insilmaril@514: \end{code}
insilmaril@514: The script above can be used to export all maps in a directory
insilmaril@514: automatically. If the script is named {\tt export-image.vys}, call \vym with
insilmaril@514: \begin{code}
insilmaril@514: \$ vym --quit --run export-image.vys *.vym
insilmaril@514: \end{code}
insilmaril@450: 
insilmaril@450: 
insilmaril@233: \section{Contributing to \vym}
insilmaril@260: So far I'd say I have written 98\% of the code on my own. No surprise,
insilmaril@260: that \vym exactly fits my own needs. Nevertheless I would like to
insilmaril@260: encourage all users of  \vym to contribute. Maybe not only with feature
insilmaril@260: requests, but also with code, new import/export filters, translations
insilmaril@260: etc. In this appendix I'll try to show how easy it is to expand the
insilmaril@260: things you can do already with \vym. I really look forward to hear from
insilmaril@260: you!
insilmaril@233: 
insilmaril@233: \subsection{Getting help}
insilmaril@233: 
insilmaril@233: \subsubsection*{Frequently asked questions}
insilmaril@233: Please refer to the FAQ available on the \vym website:
insilmaril@125: \begin{center}
insilmaril@125: \href{http://www.InSilmaril.de/vym/faq.html}{http://www.InSilmaril.de/vym/faq.html}
insilmaril@125: \end{center}
insilmaril@105: 
insilmaril@233: \subsubsection*{Mailinglists}
insilmaril@233: There are two mailinglists: {\tt vym-forum} is the \vym users forum to
insilmaril@233: discuss various questions, while {\tt vym-devel} is intended for people
insilmaril@233: interested in contributing to \vym. You can view the archives and
insilmaril@233: subscribe at
insilmaril@233: \begin{center}
insilmaril@233: \href{https://sourceforge.net/mail/?group_id=127802}{https://sourceforge.net/mail/?group\_id=127802}
insilmaril@233: \end{center}
insilmaril@233: 
insilmaril@264: \subsubsection*{Contacting the author}\label{author}
insilmaril@233: Especially for support questions please try the mailinglists first. If
insilmaril@486: everything else fails you can contact the author Uwe Drechsel at
insilmaril@233: \begin{center}
insilmaril@260: \href{mailto:vym@InSilmaril.de}{vym@InSilmaril.de}
insilmaril@233: \end{center}
insilmaril@233: 
insilmaril@233: 
insilmaril@264: 
insilmaril@264: \subsection{How to report bugs}
insilmaril@264: Though Sourceforge has its own bugreporting system, I'd rather prefer if
insilmaril@264: you contact me directly (see \ref{author}) or even better: You can file
insilmaril@264: a bugreport in Bugzilla, the bugtracking system of openSUSE:
insilmaril@264: \begin{center}
insilmaril@264: \href{http://en.opensuse.org/Submit_a_bug}{http://en.opensuse.org/Submit\_a\_bug}
insilmaril@264: \end{center}
insilmaril@264: I build \vym regulary for openSUSE, so you may report it against a
insilmaril@264: recent version there, even if you  use another Operating System.
insilmaril@486: Please don't forget to tell me what you are using:
insilmaril@264: \begin{itemize}
insilmaril@264: 	\item the exact steps needed to reproduce the bug
insilmaril@264: 	\item the version and build date of \vym (see the Help \ra About
insilmaril@264: 	\vym)
insilmaril@264: 	\item hardware and Operating System
insilmaril@264: \end{itemize}
insilmaril@264: 
insilmaril@233: \subsection{Compiling from the sources}
insilmaril@252: \subsubsection{Getting the sources} \label{getsources}
insilmaril@252: You find the latest version of \vym at the project site:
insilmaril@252: \begin{center}
insilmaril@252: \href{https://sourceforge.net/projects/vym/}{https://sourceforge.net/projects/vym/}
insilmaril@252: \end{center}
insilmaril@252: There you can check them out of the source repository (CVS):\\
insilmaril@233: 
insilmaril@252: \begin{verbatim}
insilmaril@252: cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/vym checkout code
insilmaril@252: \end{verbatim}
insilmaril@252: 
insilmaril@252: \subsubsection{The Qt toolkit}
insilmaril@233: Qt is C++ toolkit for multiplatform GUI and application development. It
insilmaril@233: provides single-source portability across MS~Windows, Mac~OS~X, Linux
insilmaril@486: and all major commercial Unix variants. Qt is also available for
insilmaril@252: embedded devices. Qt is a Trolltech product. For more information see 
insilmaril@252: \begin{center}
insilmaril@233: \href{http://www.trolltech.com/qt/}{www.trolltech.com/qt} 
insilmaril@252: \end{center}
insilmaril@233: 
insilmaril@233: 
insilmaril@252: \subsubsection{Compiling \vym }
insilmaril@233: Make sure you have installed your Qt environment properly, see the Qt
insilmaril@233: documentation for details. You need to have the Qt command {\tt qmake}
insilmaril@233: in your {\tt PATH}-environment, then run
insilmaril@514: \begin{code}
insilmaril@514: \$ qmake
insilmaril@514: $ make  
insilmaril@514: $ make install
insilmaril@514: \end{code}
insilmaril@233: The last command {\tt make install} needs root-permissions. Of course it
insilmaril@233: may be omitted, if you just want to test \vym.
insilmaril@233: 
insilmaril@260: %\subsubsection*{Compiling \vym on Macs}
insilmaril@450: %FIXME
insilmaril@233: 
insilmaril@233: \subsection{\vym file format} \label{fileformat}
insilmaril@486: \vym maps usually have the suffix "{\tt .vym}" and represent a
insilmaril@233: compressed archive of data. If you want to have a
insilmaril@233: closer look into the data structure map called "mapname.vym", 
insilmaril@233: just uncompress the map manually using
insilmaril@514: \begin{code}
insilmaril@514: \$ unzip mapname.vym
insilmaril@514: \end{code}
insilmaril@233: This will create directories named {\tt images} and {\tt flags} in your
insilmaril@233: current directory and also the map itself, usually named {\tt
insilmaril@233: mapname.xml}.
insilmaril@233: The XML structure of \vym is pretty self explaining, just have a look at
insilmaril@233: {\tt mapname.xml}.
insilmaril@233: 
insilmaril@233: This XML file can be loaded directly into \vym, it does not have to be
insilmaril@233: compressed. If you want to compress all the data yourself, use
insilmaril@514: \begin{code}
insilmaril@514: \$ zip -r mapname.vym .
insilmaril@514: \end{code}
insilmaril@233: to compress all data in your current directory.
insilmaril@233: 
insilmaril@233: \subsection{New features}
insilmaril@28: There are lots of features which might find their way into \vym.
insilmaril@233: Together with \vym you should have received a directory with several
insilmaril@514: example maps. You find them by clicking Help \ra Open~vym~example~maps.
insilmaril@514: There you will find the map {\tt vym-projectplan.vym}. It lists quite a
insilmaril@514: lot of things to be done in future. If you have more ideas, contact the
insilmaril@514: development team at {\tt vym-devel@lists.sourceforge.net}.
insilmaril@28: 
insilmaril@28: 
insilmaril@233: \subsection{New languages support}
insilmaril@252: In order to add a new language to \vym you need 
insilmaril@252: the sources (see \ref{getsources}) and
insilmaril@252: an installation of Trolltechs QT. A part of QT are the development
insilmaril@252: tools, from those tools especially the translation tool "Linguist" is
insilmaril@252: needed. 
insilmaril@252: 
insilmaril@252: In some Linux distributions the development tools are in an extra package, e.g. on SUSE LINUX you should have installed:
insilmaril@514: \begin{code}
insilmaril@514: libqt4-devel.rpm
insilmaril@514: libqt4-devel-doc.rpm
insilmaril@514: libqt4-devel-tools.rpm
insilmaril@514: \end{code}
insilmaril@252: If you don't have QT in your system, you can get it from 
insilmaril@252: 	\href{http://www.trolltech.com}{http://www.trolltech.com} Once you
insilmaril@252: 	are able to compile vym yourself, you can translate the text in vym
insilmaril@252: 	itself by performing the following steps:
insilmaril@252: \begin{itemize}
insilmaril@252: 	\item Let's assume now your encoding is "NEW" instead of for example
insilmaril@252: 	"de" for german or "en" for english
insilmaril@252: 	
insilmaril@252: 	\item Copy the file {\tt lang/vym\_en.ts} to l{\tt ang/vym\_NEW.ts} (The code
insilmaril@252: 	itself contains the english version.)
insilmaril@252: 		
insilmaril@252: 	\item Add {\tt lang/vym\_NEW.ts} to the TRANSLATIONS section of vym.pro
insilmaril@252: 
insilmaril@252: 	\item Run Linguist on {\tt vym\_NEW.ts} and do the translation
insilmaril@252: 
insilmaril@252: 	\item Run {\tt lrelease} to create {\tt vym\_NEW.qm}
insilmaril@252: 
insilmaril@252: 	\item Do a make install to install the new vym and check your translation
insilmaril@252: \end{itemize}
insilmaril@252: 
insilmaril@252: If you feel brave, you can also translate the manual. It is written in
insilmaril@252: LaTeX, you just have to change the file tex/vym.tex. (Linguist and QT
insilmaril@252: are not needed, but it is useful to know how to work with LaTeX and esp.
insilmaril@252: pdflatex to create the PDF.) 
insilmaril@252: 
insilmaril@252: Please mail me every translation you have done. I can also give you a
insilmaril@252: developer access to the project, if you want to provide translations
insilmaril@252: regulary.  
insilmaril@252: 
insilmaril@233: \subsection{New export/import filters}
insilmaril@252: \vym supports various kinds of filters. Data can be written directly,
insilmaril@252: inserted into templates or it can be written as XML data and then
insilmaril@252: processed by XSL transformations. 
insilmaril@252: 
insilmaril@252: Most of the import/export functionality is available in the classes
insilmaril@252: ImportBase and ExportBase and subclasses. All of them can be found in
insilmaril@252: {\tt imports.h} and {\tt exports.h}.
insilmaril@252: 
insilmaril@264: \subsubsection*{Direct import/export}
insilmaril@252: An example for a direct export is the XML export. This method touches
insilmaril@252: the implementation of nearly every object of \vym, so whenever possible
insilmaril@264: you should better use a XSL transformation instead.
insilmaril@252: 
insilmaril@252: If you still want to know how it is done, start looking at 
insilmaril@252: {\tt MapEditor::saveToDir} in {\tt mapeditor.cpp}.
insilmaril@252: 
insilmaril@264: \subsubsection*{Templates}
insilmaril@264: Templates have been introduced to export to opendoc format used e.g. by
insilmaril@264: Open~Office. While I read the spec ($>$ 500 pages) about the format\footnote{
insilmaril@264: \href{http://www.oasis-open.org/}{http://www.oasis-open.org/}}\ 
insilmaril@264: I had the feeling that I did not want to write the export from scratch. 
insilmaril@264: It would be too complex to adapt the styles to your own wishes, e.g. the
insilmaril@264: layout.
insilmaril@252: 
insilmaril@264: Instead I analyzed existing Open~Office documents. I found out that
insilmaril@264: there are lots of redundant bits of information in a standard
insilmaril@264: presentation, for example each list item is contained in its own list.
insilmaril@264: In the end I came up with the default presentation style, which still
insilmaril@264: could be simplified, just in case you have free time\ldots
insilmaril@252: 
insilmaril@486: The existing templates are still work in progress, before you spend too
insilmaril@264: much time developing your own style, please contact me.  Basically the
insilmaril@264: following steps are needed to build your own style:
insilmaril@264: \begin{enumerate}
insilmaril@264: 	\item Create an example in Open Office. Use a title, authors name,
insilmaril@264: 	page heading etc.\ which you can easily grep for in the output file.
insilmaril@264: 	
insilmaril@264: 	\item Unzip  the Open Office document into a directory.
insilmaril@264: 
insilmaril@264: 	\item The main file is called {\tt content.xml}. All data is in one
insilmaril@264: 	single line. You can split the XML tags using the script {\tt
insilmaril@264: 	scripts/niceXML}, which is part of the \vym distribution.
insilmaril@264: 
insilmaril@264: 	\item Copy the output of {\tt niceXML} to {\tt
insilmaril@264: 	content-template.xml}.
insilmaril@264: 
insilmaril@264: 	\item Looking closer you will find lots of unused definitions, for
insilmaril@264: 	example of styles. You can delete or simply ignore them.
insilmaril@264: 
insilmaril@264: 	\item Try to find your title, authors name. \vym will replace the
insilmaril@264: 	following strings while exporting:
insilmaril@264: 	\begin{center}
insilmaril@264: 	\begin{tabular}{lp{4cm}}
insilmaril@264: 		{\tt <!-- INSERT TITLE -->}		& title of map \\
insilmaril@264: 		{\tt <!-- INSERT AUTHOR-->	}	& author \\
insilmaril@264: 		{\tt <!-- INSERT COMMENT -->}	& comment \\
insilmaril@264: 		{\tt <!-- INSERT PAGES-->}		& content of map \\
insilmaril@264: 	\end{tabular}
insilmaril@264: 	\end{center}
insilmaril@264: 	The content itself is generated in a similar way by inserting lists
insilmaril@264: 	into {\tt page-template}. Here the following substitutions are made:
insilmaril@264: 	\begin{center}
insilmaril@264: 	\begin{tabular}{lp{7cm}}
insilmaril@264: 		{\tt <!-- INSERT PAGE HEADING-->}		& heading of a page
insilmaril@264: 		(mainbranch or child of mainbranch, depending on the use of
insilmaril@264: 		sections) \\
insilmaril@640: 		{\tt <!-- INSERT LIST -->	}	& all children of the branch above \\
insilmaril@264: 	\end{tabular}
insilmaril@264: 	\end{center}
insilmaril@264: \end{enumerate}
insilmaril@264: Currently images are exported and notes just will appear as text
insilmaril@486: without formatting and colours.
insilmaril@264: 
insilmaril@264: 
insilmaril@264: 
insilmaril@264: 
insilmaril@264: \subsubsection*{XSL Transformation}
insilmaril@264: \vym uses XSL transformations while exporting (e.g. XHTML) and importing
insilmaril@264: data (e.g. KDE bookmarks). There is a little code needed to provide the
insilmaril@264: GUI, the rest is done using the {\tt .xsl} stylesheet and calling the
insilmaril@264: {\tt xsltproc} processor, which is part of libxslt, the XSLT
insilmaril@264: C  library  for  GNOME. 
insilmaril@233: 
insilmaril@233: \end{appendix}
insilmaril@233: \end{document}
insilmaril@28: 
insilmaril@125: %TODO
insilmaril@125: %\subsubsection{Menus}
insilmaril@125: %\subsubsection{Keyboard shortcuts}
insilmaril@125: %Where does vym save its settings? -> ~/.qt/vymrc
insilmaril@125: 
insilmaril@28: 
insilmaril@28: % INDEX
insilmaril@28: % mapeditor
insilmaril@28: % noteditor
insilmaril@28: % branch
insilmaril@28: % mapcenter
insilmaril@28: % heading
insilmaril@28: % flag
insilmaril@28: % orientation 
insilmaril@28: % zoom
insilmaril@28: % orientation
insilmaril@28: % Toolbar
insilmaril@28: % Zoom
insilmaril@28: % Find
insilmaril@28: % statusbar
insilmaril@28: % link
insilmaril@28: % mainbranch
insilmaril@28: % subtree
insilmaril@28: % reorder
insilmaril@28: % scroll
insilmaril@28: % fold
insilmaril@104: % vymlink
insilmaril@104: % xlink
insilmaril@125: % modMode
insilmaril@104: % context menu
insilmaril@104: % Mac OS X
insilmaril@28: 
insilmaril@28: 
insilmaril@28: 
insilmaril@125: \end{document}




