# The &kdissert; Handbook

## Introduction

&kdissert; is a program for the creation of mindmaps containing text, pictures, comments and links, and their transformation into Documents like reports and presentations. &kdissert; currently features LaTeX (presentations using Beamer or Prosper, pdf report and article), OpenOffice.org Writer and Impress, plain text and html document generators. This tool can be very useful for students, but also for teachers, businessmen and people who need to make presentations in a hurry.

## Working with kdissert

The recommended workflow is the following :

- Start by adding objects - add as many unique ideas as possible

- Switch to link mode and start linking your ideas

- Delete irrelevant objects, balance the tree (3-4 objects by branch on the average, no more than 5 ancestors)

- Add text and pictures to the map objects - the more, the better (in reports, pictures especially)

- Switch to sort mode and sort the branches by order of relevance

- Generate your documents and work on them (LaTeX, OpenOffice, ..)

## Quickstart

&kdissert; 0.3.8 &kdissert; screenshot

First, you will create a mindmap of your ideas using the mind map view (first tab on the kdissert gui). Maximize the window to make as much space available as possible, right-click on the canvas (in the middle of the map) and choose 'new item' to create a root.

It is also possible to double-click on the canvas view to create new mindmap items. To delete items, just press the delete key when some items are selected. By default, roots of mindmap trees are coloured in yellow, while leaves are coloured in green.

Use the point mode (cursor icon) to switch to point mode. You can now select items and drag them to make more space available for new items (use the arrow keys while holding the left mouse button pressed). When left-clicking onto the canvas and dragging around, a rubberband appears for selecting mindmap items more easily. Multiple items can also be selected by holding the shift key pressed, and left-clicking on the mindmap items sequentially.

Use the link mode (cross icon) to connect an item to a parent item or to a root item. For this, left-click on an item, and while holding the mouse button pressed, drag the thread that appears to another item. The connections can start from any item, but must stop on an unconnected item (yellow color).

The document generators need the items to be sorted, to know which mindmap branches come first. To sort the items, select the sort mode (icon with numbers) and click on an item. Numbers appear near the children of the item selected (yellow discs). Click on the numbers sequentially to sort them.

The document generators are powerful tools to help reusing the mindmap information, they are accessible through the Tools menu. Instructions are provided in the wizard for how to use the documents properly, so please read carefully the information displayed in the dialog boxes.

It is finally possible to take a picture of the mindmap obtained by choosing the picture export through the Tools menu. The picture output is a PNG file which can be reused in most graphic tools.

## Advanced features

You can type the summary directly in the mindmap view when an object is selected. When no item is selected, the object that was selected last is used.

The shortcut ctrl+scroll wheel can increase or decrease the fonts of selected objects.

When in select mode, double clicking with control key pressed disconnect an object from its parent. Double-clicking on a link with the control key held disconnects it too. Clicking sequentially on two objects with the control key held links them.

The move mode (icon with a lens) can be useful when dealing with huge mindmaps. To use it, left-click on the mindmap view, hold the mouse button pressed, and drag around to translate the view.

To switch between the point, link, sort and move modes faster, the following default keys are assigned : 'f' for point, 'd' for link, 's' for sort and 'a' for move. These shortcuts can be changed in the shortcut editor, accessible through the settings menu.

The linear view can be used for seeing the mindmap in a flat way. Drag and drop, and some actions are implemented : delete (delete key), demote ('o' key) and promote ('p' key).

The document generators usually take the biggest tree to generate the document, so small trees and orphans will be left aside.

To center the view on the root of the biggest tree in the mindmap view, use the shortcut 'ctrl+h'.

To make the mindmap more meaningful, it is possible to change the colors and fonts - the menus are available by right-clicking onto items (both mindmap and linear views). This also applies to groups of mindmap items selected.

Hold the ctrl+key pressed and use the mousewheel on an item, or on a group of selected items to increase the fonts.

Hold the ctrl+key pressed in link mode to make references. They are currently used in LaTeX article and book generators. To remove a reference, right-click on one and look in the disconnect submenu that appears in the popup.

The mindmap tree can be browsed using the shortcuts control+arrows. Selected objects can be moved using alt+arrows.

Use the little square on the top-right corner of panels to make them stay. The shortcuts F2 and F3 make it possible to switch the focus between the map and the text panel

Dragging and dropping text onto the mindmap view or onto mindmap objects is possible.

## Settings

The document properties for new documents are applied to new documents only. To change the properties of the current document, use Edit, Document properties.

The default font represents the font used for the mindmap accessories (labels for sorting the items), and the initial font used by mindmap items. Mindmap items from other .kdi files keep their font as settings. To change the fonts for all items, you will have to select them and apply a new font (right-click on the mindmap view and choose the font setttings).

The thumbnail size represent the size of the pictures previews that are made visible on the mindmap view (for items that have a picture). Those previews can be turned off by unchecking the appropriate checkbox.

## Developer's Guide to &kdissert;

To start hacking on kdissert, one should first start by consulting the README, ROADMAP and HACKING files included in the source distribution. Contrary to most kde projects, the kdissert build system is based on scons and bksys, which is much-more developer-friendly than other ones. Several (failed) attempts have been made for using qmake instead, and so far scons seems to be the best solution.

To create new kdissert plugins, one should take one of the existing generators in src/templates (for example : kdissasciidoc), change the name (keeping the "kdiss" prefix), and create a library. The .h and .cpp files will need to be modified (change the names). The content of the SConscript files will also need to be modified.

A tarball, named like "kdissPLUGIN.tar.gz" is required for the document generation. It will not work if no such file is available. It is highly recommended to include a README file in that archive.

## Questions and Answers

&reporting.bugs; &updating.documentation;

I can't create any mindmap item ?

Double-click or use the right mouse button on the mindmap view ..

How to remove a reference ?

Right-click on the reference and choose disconnect->reference

The feature xxx isn't available ?

The program is not finished yet - you are welcome to participate to it, please refer to the files ROADMAP and HACKING available in the source distribution.

## Credits and License

&kdissert;

Program copyright 2003, 2004, 2005 Thomas Nagy tnagy2^8@yahoo.fr

&underGPL;

Documentation copyright 2004, 2005 Thomas Nagy tnagy2^8@yahoo.fr

&underFDL;

## Installation

### How to obtain &kdissert;

The kdissert homepage is here When unavailable, the project can be found there

### Requirements

In order to successfully use &kdissert;, you need &kde; 3.2 (at least) and python 2.3

The required libraries can be found on The kde ftp site.

### Compilation and Installation

If you have scons on your system, use : scons; scons install

Else, use ./unpack_local_scons.sh; make; make install

&documentation.index;