Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdesdk@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

27 files changed, 1462 insertions, 0 deletions

diff --git a/doc/umbrello/Makefile.am b/doc/umbrello/Makefile.am
new file mode 100644
index 00000000..45fb6fde
--- /dev/null
+++ b/doc/umbrello/Makefile.am
@@ -0,0 +1,2 @@
+KDE_LANG = en
+KDE_DOCS = umbrello
diff --git a/doc/umbrello/activity-diagram.png b/doc/umbrello/activity-diagram.png
new file mode 100644
index 00000000..75234476
--- /dev/null
+++ b/doc/umbrello/activity-diagram.png
diff --git a/doc/umbrello/add-remove-languages.png b/doc/umbrello/add-remove-languages.png
new file mode 100644
index 00000000..42c1d908
--- /dev/null
+++ b/doc/umbrello/add-remove-languages.png
diff --git a/doc/umbrello/aggregation.png b/doc/umbrello/aggregation.png
new file mode 100644
index 00000000..46050842
--- /dev/null
+++ b/doc/umbrello/aggregation.png
diff --git a/doc/umbrello/association.png b/doc/umbrello/association.png
new file mode 100644
index 00000000..ac984111
--- /dev/null
+++ b/doc/umbrello/association.png
diff --git a/doc/umbrello/authors.docbook b/doc/umbrello/authors.docbook
new file mode 100644
index 00000000..1a079f02
--- /dev/null
+++ b/doc/umbrello/authors.docbook
@@ -0,0 +1,41 @@
+<chapter id="authors">
+<title>Authors and History</title>
+<para>
+This project was started by Paul Hensgen as one of his University projects.
+The original name of the application was <application>UML Modeller</application>.  Paul did
+all the development until the end of 2001 when the program reached version 1.0.
+</para>
+<para>
+Version 1.0 already offered a lot of functionality, but after the project had been reviewed at
+Paul's University, other developers could join and they started making valuable contributions
+to <application>UML Modeller</application>, like switching from a binary file format to an &XML; file, support for more
+types of &UML; Diagrams, Code Generation and Code Import just to name a few.
+</para>
+<para>
+Paul had to retire from the development team in Summer 2002 but, as Free and Open Source Software, the
+program continues to improve and evolve and is being maintained by a group of developers from different
+parts of the world. In September 2002 the project changed its name from <application>&UML; Modeller</application>, to
+&umbrello;. There are several reasons for the change of names, the most
+important ones being that just <quote>uml</quote> &mdash; as it was commonly known &mdash; was a much too generic name
+and caused problems with some distributions. The other important reason is that the developers think
+<application>Umbrello</application> is a much cooler name.
+</para>
+<para>
+The development of &umbrello; as well as discussions as to where the program should head for future versions
+is open and takes place over the Internet. If you would like to contribute to the project, please do not
+hesitate to contact the developers. There are many ways in which you can help &umbrello;:
+</para>
+<itemizedlist>
+<listitem><para>Reporting bugs or improvements suggestions</para></listitem>
+<listitem><para>Fixing bugs or adding features</para></listitem>
+<listitem><para>Writing good documentation or translating it to other languages</para></listitem>
+<listitem><para>And of course...coding with us!</para></listitem>
+</itemizedlist>
+<para>
+As you see, there are many ways in which you can contribute. All of them are very important and
+everyone is welcome to participate.
+</para>
+<para>
+The &umbrello; developers can be reached at <email>uml-devel@lists.sourceforge.net</email>.
+</para>
+</chapter>
diff --git a/doc/umbrello/class-diagram.png b/doc/umbrello/class-diagram.png
new file mode 100644
index 00000000..3b12a4f6
--- /dev/null
+++ b/doc/umbrello/class-diagram.png
diff --git a/doc/umbrello/class.png b/doc/umbrello/class.png
new file mode 100644
index 00000000..9c12a849
--- /dev/null
+++ b/doc/umbrello/class.png
diff --git a/doc/umbrello/code-import.png b/doc/umbrello/code-import.png
new file mode 100644
index 00000000..49f477e5
--- /dev/null
+++ b/doc/umbrello/code-import.png
diff --git a/doc/umbrello/code_import_and_generation.docbook b/doc/umbrello/code_import_and_generation.docbook
new file mode 100644
index 00000000..8beffcc3
--- /dev/null
+++ b/doc/umbrello/code_import_and_generation.docbook
@@ -0,0 +1,170 @@
+<chapter id="code-import-generation">
+<title>Code Import and Code Generation</title>
+<para>
+&umbrello; is a &UML; modelling tool, and as such its main purpose is to help you in the 
+<emphasis>analysis and design</emphasis> of your systems. However, to make the transition
+between your design and your <emphasis>implementation</emphasis>, &umbrello; allows you to
+generate source code in different programming languages to get you started. Also, if you 
+want to start using &UML; in an already started C++ project, &umbrello; can help you create a model
+of your system from the source code by analysing your source code and importing the classes
+found in it.
+</para>
+<sect1 id="code-generation">
+<title>Code Generation</title>
+<para>
+&umbrello; can generate source code for various programming languages based on your &UML; Model
+to help you get started with the implementation of your project. The code generated consists
+of the class declarations, with their methods and attributes so you can <quote>fill in the
+blanks</quote> by providing the functionality of your classes' operations.
+</para>
+<para>
+&umbrello; 1.2 comes with code generation support for ActionScript, Ada, C++, CORBA IDL, &Java;, JavaScript, <acronym>PHP</acronym>, Perl, Python, SQL and XMLSchema. 
+</para>
+<sect2 id="generate-code">
+<title>Generating Code</title>
+<para>
+In order to generate code with &umbrello;, you first need to create or load a Model
+containing at least one class. When you are ready to start writing some code, select the
+<guimenuitem>Code Generation Wizard</guimenuitem> entry from the <guimenuitem>Code</guimenuitem> menu to 
+start a wizard which will guide you trough the code generation process.
+</para>
+<para>
+The first step is to select the classes for which you want to generate source code.
+By default all the classes of your model are selected, and you can remove the ones
+for which you do not want to generate code by moving them to the left-hand side list.
+</para>
+<para>
+The next step of the wizard allows you to modify the parameters the Code Generator uses
+while writing your code. The following options are available:
+</para>
+<para>
+<screenshot>
+<screeninfo>Code Generation Options</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="generation-options.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Options for the Code Generation in &umbrello;</phrase>
+	  </textobject>
+	  <caption>
+	    <para>Options for the Code Generation in &umbrello;
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+</para>
+<sect3 id="generation-options">
+<title>Generation Options</title>
+<!-- LW; to rearrange -->
+
+<sect4>
+<title>Code Verbosity</title>
+<para>
+The option <guilabel>Write documentation comments even if empty</guilabel> instructs the
+ Code Generator to write comments of the /** blah */ style even if the comment blocks are empty.
+If you added documentation to your classes, methods or attributes in your Model, the
+Code Generator will write these comments as <application>Doxygen</application> documentation regardless of what you set here, but
+if you select this option &umbrello; will write comment blocks for all classes, methods and attributes
+even if there is no documentation in the Model, in which case you should document your classes
+later directly in the source code.
+</para>
+<para>
+<guilabel>Write comments for sections even if section is empty</guilabel> causes &umbrello; to write comments
+in the source code to delimit the different sections of a class. For example <quote>public methods</quote>
+ or <quote>Attributes</quote> before the corresponding sections. If you select this option &umbrello; 
+ will write comments for all sections of the class even if the section is empty. For example,
+ it would write a comment saying <quote>protected methods</quote> even if there are no protected 
+ methods in your class.
+</para>
+</sect4>
+<sect4>
+<title>Folders</title>
+<para>
+<guilabel>Write all generated files to folder</guilabel>. Here you should select the folder 
+where you want &umbrello; to put the generated sources.
+</para>
+<para>
+The <guilabel>Include heading files from folder</guilabel> option allows you to insert a 
+heading at the beginning of each generated file. Heading files can contain copyright or licensing
+ information and contain variables that are evaluated at generation time. You can take a look
+ at the template heading files shipped with &umbrello; to see how to use this variables for replacing
+ your name or the current date at generation time.
+</para>
+</sect4>
+<sect4>
+<title>Overwrite Policy</title>
+<!-- FIXME update for Umbrello 1.2's new C++ and Java code generators -->
+<para>
+This option tells &umbrello; what to do if the file it wants to create already exists in
+the destination folder. &umbrello; <emphasis>cannot modify existing source files</emphasis>,
+so you have to choose between overwriting the existing file, skipping the generation of
+that particular file or letting &umbrello; choose a different file name. If you choose the option
+to use a different name, &umbrello; will add a suffix to the file name.
+</para>
+</sect4>
+<sect4>
+<title>Language</title>
+<para>
+&umbrello; will by default generate code in the language you have selected as Active Language, but
+with the Code Generation Wizard you have the option to change this to another language.
+</para>
+</sect4>
+</sect3><!--generation-options-->
+<sect3 id="generation-wizard-generation">
+<title>Generation Wizard Generation</title>
+<para>
+The third and last step of the wizard shows the status of the Code Generation process.
+You need only to click on the Generate button to get your classes written for you.
+</para>
+<para>
+Note that the Options you select during the Code Generation Wizard are only valid for the current
+generation. The next time you run the wizard you will need to re-select all the options
+(your headings folder, overwrite policy, and so on). You can set the defaults used by &umbrello; 
+in the <guilabel>Code Generation</guilabel> section of the &umbrello; settings, available
+at <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &umbrello;...</guimenuitem></menuchoice>
+</para>
+<para>
+If you have set your Code Generation options to the right settings and want to generate
+some code right away without going through the wizard, you can select the entire 
+<guimenuitem>Generate All Code</guimenuitem> from the Code menu. 
+This will generate code for all the classes in your Model using the current settings 
+(including Output Folder and Overwrite Policy, so use with care).
+</para>
+</sect3>
+</sect2><!--generate-code-->
+</sect1> <!--code-generation-->
+<sect1 id="code-import">
+<title>Code Import</title>
+<para>
+&umbrello; can import source code from your existing projects to help you build Model of 
+your systems. &umbrello; 1.2 supports only C++ source code, but other languages
+should be available in future versions.
+</para>
+<para>
+To import classes into your Model, select the entry <guimenuitem>Import Classes...</guimenuitem> from
+the <guimenu>Code</guimenu> menu. In the file dialog select the files containing the C++
+class declarations and press OK. The classes will be imported and you will find them as part of
+your Model in the Tree View. Note that &umbrello; will not create any kind of Diagram for showing
+your classes, they will only be imported into your Model so that you can use them later in any 
+diagram you want.
+</para>
+<para>
+<screenshot>
+<screeninfo>Code Import</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="code-import.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Menu for importing source code in &umbrello;</phrase>
+	  </textobject>
+	  <caption>
+	    <para>Menu for importing source code in &umbrello;
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+</para>
+</sect1>
+</chapter> <!--code-import-generation-->
diff --git a/doc/umbrello/collaboration-diagram.png b/doc/umbrello/collaboration-diagram.png
new file mode 100644
index 00000000..681d5c77
--- /dev/null
+++ b/doc/umbrello/collaboration-diagram.png
diff --git a/doc/umbrello/composition.png b/doc/umbrello/composition.png
new file mode 100644
index 00000000..ad07e1d9
--- /dev/null
+++ b/doc/umbrello/composition.png
diff --git a/doc/umbrello/credits.docbook b/doc/umbrello/credits.docbook
new file mode 100644
index 00000000..807089a5
--- /dev/null
+++ b/doc/umbrello/credits.docbook
@@ -0,0 +1,12 @@
+<chapter id="copyright">
+<title>Copyright</title>
+
+<para>Copyright 2001, Paul Hensgen</para>
+<para>Copyright 2002, 2003 The &umbrello; Authors. See 
+<ulink url="http://uml.sf.net/developers.php">http://uml.sf.net/developers.php</ulink> 
+for more information</para>
+
+&underFDL;
+&underGPL;
+
+</chapter>
diff --git a/doc/umbrello/folders.png b/doc/umbrello/folders.png
new file mode 100644
index 00000000..59680d97
--- /dev/null
+++ b/doc/umbrello/folders.png
diff --git a/doc/umbrello/generalization.png b/doc/umbrello/generalization.png
new file mode 100644
index 00000000..8236cca3
--- /dev/null
+++ b/doc/umbrello/generalization.png
diff --git a/doc/umbrello/generation-options.png b/doc/umbrello/generation-options.png
new file mode 100644
index 00000000..37c05697
--- /dev/null
+++ b/doc/umbrello/generation-options.png
diff --git a/doc/umbrello/index.docbook b/doc/umbrello/index.docbook
new file mode 100644
index 00000000..0da7c91e
--- /dev/null
+++ b/doc/umbrello/index.docbook
@@ -0,0 +1,69 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.1//EN"
+ "dtd/kdex.dtd" [
+ <!ENTITY umbrello "<application>Umbrello &UML; Modeller</application>">
+ <!ENTITY kappname "&umbrello;">
+ <!ENTITY packagename "kdesdk">
+ <!ENTITY UML "<acronym>UML</acronym>">
+ <!ENTITY introduction-chapter SYSTEM "introduction.docbook">
+ <!ENTITY uml-basics-chapter SYSTEM "uml_basics.docbook">
+ <!ENTITY working-with-umbrello-chapter SYSTEM "working_with_umbrello.docbook">
+ <!ENTITY code-import-and-generation-chapter SYSTEM "code_import_and_generation.docbook">
+ <!ENTITY other-features-chapter SYSTEM "other_features.docbook">
+ <!ENTITY authors-chapter SYSTEM "authors.docbook">
+ <!ENTITY credits-chapter SYSTEM "credits.docbook">
+ <!ENTITY % addindex "IGNORE">
+ <!ENTITY % English "INCLUDE"><!-- change language only here -->
+  <!-- Do not define any other entities; instead, use the entities
+       from kde-genent.entities and $LANG/user.entities. -->
+]>
+
+<book id="Umbrello" lang="&language;">
+<bookinfo>
+<title>&umbrello; Handbook</title>
+
+<authorgroup>
+<corpauthor>&umbrello; Authors</corpauthor>
+</authorgroup>
+
+<copyright>
+<year>2001</year>
+<holder>Paul Hensgen</holder>
+</copyright>
+<copyright>
+<year>2002, 2003</year>
+<holder>&umbrello; Authors</holder>
+</copyright>
+
+
+<date>2003-10-15</date>
+<releaseinfo>1.2</releaseinfo>
+
+<abstract>
+<para>
+&umbrello; helps the software development
+process by using the industry standard Unified Modelling Language (&UML;) 
+to enable you to create diagrams for designing and documenting your systems.
+</para>
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>UML</keyword>
+<keyword>modelling</keyword>
+<keyword>diagrams</keyword>
+<keyword>software development</keyword>
+<keyword>development</keyword>
+</keywordset>
+
+</bookinfo>
+
+&introduction-chapter;
+&uml-basics-chapter;
+&working-with-umbrello-chapter;
+&code-import-and-generation-chapter;
+&other-features-chapter;
+&authors-chapter;
+&credits-chapter;
+
+</book>
diff --git a/doc/umbrello/introduction.docbook b/doc/umbrello/introduction.docbook
new file mode 100644
index 00000000..3af9f719
--- /dev/null
+++ b/doc/umbrello/introduction.docbook
@@ -0,0 +1,43 @@
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>
+&umbrello; is a &UML; diagram tool that can support you
+in the software development process.
+Especially during the analysis and design phases of this process, &umbrello; will help you to
+get a high quality product. &UML; can also be used to document your software designs to help you and your
+fellow developers.
+</para>
+<para>
+Having a good model of your software is the best way to communicate with
+other developers working on the project and with your customers. A good model
+is extremely important for medium and big-size projects, but it is also very useful
+for small ones. Even if you are working on a small one man project you
+will benefit from a good model because it will give you an overview that will help
+you code things right the first time.
+</para>
+<para>
+&UML; is the diagramming language used to describing such models. You can represent your ideas in &UML;
+using different types of diagrams. &umbrello; 1.2 supports the following types:
+</para>
+<itemizedlist>
+<listitem><para>Class Diagram</para></listitem>
+<listitem><para>Sequence Diagram</para></listitem>
+<listitem><para>Collaboration Diagram</para></listitem>
+<listitem><para>Use Case Diagram</para></listitem>
+<listitem><para>State Diagram</para></listitem>
+<listitem><para>Activity Diagram</para></listitem>
+<listitem><para>Component Diagram</para></listitem>
+<listitem><para>Deployment Diagram</para></listitem>
+</itemizedlist>
+<para>
+More information about &UML; can be found at the website of
+<ulink url="http://www.omg.org"><acronym>OMG</acronym>, http://www.omg.org</ulink> who create the &UML; standard.
+</para>
+<para>
+We hope you enjoy &umbrello; and that it helps you create high quality software.
+&umbrello; is Free Software and available at no cost, the only thing we ask from you is to report any bugs, problems, or suggestions
+to the &umbrello; developers at <email>uml-devel@lists.sourceforge.net</email> or 
+<ulink url="http://bugs.kde.org">http://bugs.kde.org</ulink>.
+</para>
+</chapter>
diff --git a/doc/umbrello/other_features.docbook b/doc/umbrello/other_features.docbook
new file mode 100644
index 00000000..1f368622
--- /dev/null
+++ b/doc/umbrello/other_features.docbook
@@ -0,0 +1,61 @@
+<chapter id="other-features">
+<title>Other Features</title>
+<sect1> 
+<title>Other &umbrello; Features</title>
+<para>This chapter will briefly explain some other features &umbrello; offers you.</para>
+<sect2 id="copying-as-png">
+<title>Copying objects as PNG images</title>
+<para>
+Apart from offering you the normal copy, cut and paste functionality that you would expect to copy
+objects between different diagrams, &umbrello; can copy the objects as PNG pictures so that you can
+insert them into any other type of document. You do not need to do anything special to use this feature,
+just select an object from a diagram (Class, Actor, &etc;) and copy it (<keycombo>&Ctrl;<keycap>C</keycap></keycombo>,
+ or using the menu), then open a &kword; document (or any program into which you can paste images) and select <guimenuitem>Paste</guimenuitem>. This is a great feature
+to export parts of your diagram as simple pictures.
+</para>
+</sect2>
+<sect2 id="export-as-png">
+<title>Exporting to an Image</title>
+<para>
+You can also export a complete diagram as an image. The only thing you need to do is select
+the diagram you want to export, and then the option <guimenuitem>Export as Picture...</guimenuitem> from
+the <guimenu>Diagram</guimenu> menu.
+</para>
+</sect2>
+<sect2 id="printing">
+<title>Printing</title>
+<para>
+&umbrello; allows you to print individual diagrams. Press the <guiicon>Print</guiicon> button on the
+ application toolbar or selecting the <guimenuitem>Print</guimenuitem> option from the
+<guimenu>File</guimenu> menu will give you a standard &kde; Print dialog from where you can print
+your diagrams.
+</para>
+</sect2>
+<sect2 id="logical-folders">
+<title>Logical Folders</title>
+<para>
+To better organize your model, especially for larger projects, you can create logical folders in
+the Tree View. Just select the option <menuchoice><guimenu>New</guimenu><guimenuitem>Folder</guimenuitem></menuchoice> from the context menu
+of the default folders in the Tree View to create them. Folders can be nested, and you can
+move objects around by dragging them from one folder and dropping them into another.
+</para>
+
+<screenshot>
+<screeninfo>Organizing your Model with Folders</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="folders.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Organizing a Model with Logical Folders in &umbrello;</phrase>
+	  </textobject>
+	  <caption>
+	    <para>Organizing a Model with Logical Folders in &umbrello;
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+
+</sect2>
+</sect1>
+</chapter>
diff --git a/doc/umbrello/sequence-diagram.png b/doc/umbrello/sequence-diagram.png
new file mode 100644
index 00000000..a5f9fbbc
--- /dev/null
+++ b/doc/umbrello/sequence-diagram.png
diff --git a/doc/umbrello/state-diagram.png b/doc/umbrello/state-diagram.png
new file mode 100644
index 00000000..610b2133
--- /dev/null
+++ b/doc/umbrello/state-diagram.png
diff --git a/doc/umbrello/umbrello-main-screen.png b/doc/umbrello/umbrello-main-screen.png
new file mode 100644
index 00000000..52c48734
--- /dev/null
+++ b/doc/umbrello/umbrello-main-screen.png
diff --git a/doc/umbrello/umbrello-ui-clean.png b/doc/umbrello/umbrello-ui-clean.png
new file mode 100644
index 00000000..8b147866
--- /dev/null
+++ b/doc/umbrello/umbrello-ui-clean.png
diff --git a/doc/umbrello/umbrello-ui.png b/doc/umbrello/umbrello-ui.png
new file mode 100644
index 00000000..ee3d5911
--- /dev/null
+++ b/doc/umbrello/umbrello-ui.png
diff --git a/doc/umbrello/uml_basics.docbook b/doc/umbrello/uml_basics.docbook
new file mode 100644
index 00000000..e9ad0d0d
--- /dev/null
+++ b/doc/umbrello/uml_basics.docbook
@@ -0,0 +1,616 @@
+<chapter id="uml-basics">
+<title>&UML; Basics</title>
+<sect1 id="about-uml">
+<title>About &UML;</title>
+<para>
+This chapter will give you a quick overview of the basics of &UML;. Keep in mind
+that this is not a comprehensive tutorial on &UML; but rather a brief introduction to &UML; which can be read as a &UML; tutorial. 
+If you would like to learn more about the
+Unified Modelling Language, or in general about software analysis and design, refer to one of the
+many books available on the topic. There are also a lot of tutorials on the Internet which you
+can take as a starting point.
+</para>
+
+<para>
+The Unified Modelling Language (&UML;) is a diagramming language or notation to specify, visualize and document
+models of Object Orientated software systems. &UML; is not a development method, that means it does not tell you
+what to do first and what to do next or how to design your system, but it helps you to visualize
+your design and communicate with others. &UML; is controlled by the Object Management Group (<acronym>OMG</acronym>) and is the
+industry standard for graphically describing software.
+</para>
+<para>
+&UML; is designed for Object Orientated software design and has limited use for other programming paradigms.
+</para>
+<para>
+&UML; is composed of many model elements that represent the different parts of a software system.
+The &UML; elements are used to create diagrams, which represent a certain part, or a point of view of
+the system.
+The following types of diagrams are supported by &umbrello;:
+</para>
+
+<itemizedlist>
+
+<listitem><para><emphasis><link linkend="use-case-diagram">Use Case
+Diagrams</link></emphasis> show actors (people or other users of the
+system), use cases (the scenarios when they use the system), and their
+relationships</para> </listitem>
+
+<listitem><para><emphasis><link linkend="class-diagram">Class
+Diagrams</link></emphasis> show classes and the relationships between
+them</para> </listitem>
+
+<listitem><para><emphasis><link linkend="sequence-diagram">Sequence
+Diagrams</link></emphasis> show objects and a sequence of method calls
+they make to other objects.</para> </listitem>
+
+<listitem><para><emphasis><link
+linkend="collaboration-diagram">Collaboration
+Diagrams</link></emphasis> show objects and their relationship,
+ putting emphasis on the objects that participate in the message exchange</para>
+</listitem>
+
+<listitem><para><emphasis><link linkend="state-diagram">State
+Diagrams</link></emphasis> show states, state changes and events in an
+object or a part of the system</para> </listitem>
+
+<listitem><para><emphasis><link linkend="activity-diagram">Activity
+Diagrams</link></emphasis> show activities and the changes from one
+activity to another with the events occurring in some part of the
+system</para></listitem>
+
+<listitem><para><emphasis><link linkend="component-diagram">Component
+Diagrams</link></emphasis> show the high level programming components
+(such as KParts or Java Beans).</para></listitem>
+
+<listitem><para><emphasis><link
+linkend="deployment-diagram">Deployment Diagrams</link></emphasis> show
+the instances of the components and their
+relationships.</para></listitem> 
+
+</itemizedlist>
+
+</sect1>   <!-- about-uml -->
+
+<sect1 id="uml-elements">  
+<title>&UML; Elements</title>
+<sect2 id="use-case-diagram">
+<title>Use Case Diagram</title>
+<para>Use Case Diagrams describe the relationships and dependencies between a group of <emphasis>Use Cases</emphasis>
+and the Actors participating in the process.</para>
+<para>It is important to notice that Use Case Diagrams are not suited to represent the design,
+and cannot describe the internals of a system. Use Case Diagrams are meant to facilitate the communication
+with the future users of the system, and with the customer, and are specially helpful to determine the required
+features the system is to have. Use Case Diagrams tell, <emphasis>what</emphasis> the system
+should do but do not &mdash; and cannot &mdash; specify <emphasis>how</emphasis> this is to be achieved.</para>
+<para>
+<screenshot>
+<screeninfo>An example Use Case diagram.</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="use-case-diagram.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&umbrello; showing a Use Case Diagram</phrase>
+	  </textobject>
+	  <caption>
+	    <para>&umbrello; showing a Use Case Diagram
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+</para>
+<sect3 id="use-case">
+<title>Use Case</title>
+<para>A <emphasis>Use Case</emphasis> describes &mdash; from the point of view of the actors &mdash; a group of activities
+in a system that produces a concrete, tangible result.</para>
+<para>
+Use Cases are descriptions of the typical interactions between the users of a system and the system itself.
+They represent the external interface of the system and specify a form of requirements of what the
+system has to do (remember, only what, not how).
+</para>
+<para>When working with Use Cases, it is important to remember some simple rules:
+ <itemizedlist>
+ <listitem><para>Each Use Case is related to at least one actor</para></listitem>
+ <listitem><para>Each Use Case has an initiator (&ie; an actor)</para></listitem>
+ <listitem><para>Each Use Case leads to a relevant result (a result with <quote>business value</quote>)</para>
+ </listitem>
+ </itemizedlist>
+</para>
+<para>
+Use Cases can also have relationships with other Use Cases. The three most typical types of relationships
+between Use Cases are:</para>
+<itemizedlist>
+<listitem><para><emphasis>&lt;&lt;include&gt;&gt;</emphasis> which specifies that a Use Case takes place <emphasis>inside</emphasis>
+another Use Case</para></listitem>
+<listitem><para><emphasis>&lt;&lt;extends&gt;&gt;</emphasis> which specifies that in certain situations, or at some point (called an
+extension point) a Use Case will be extended by another.</para></listitem>
+<listitem><para><emphasis>Generalization</emphasis> specifies that a Use Case inherits the characteristics
+of the <quote>Super</quote>-Use Case, and can override some of them or add new ones in a similar way as the
+inheritance between classes.
+</para>
+</listitem>
+</itemizedlist>
+</sect3>
+<sect3 id="actor">
+<title>Actor</title>
+<para>
+An actor is an external entity (outside of the system) that interacts with the system by participating
+(and often initiating) a Use Case. Actors can be in real life people (for example users of the system),
+other computer systems or external events.
+</para>
+<para>
+Actors do not represent the <emphasis>physical</emphasis> people or systems, but their <emphasis>role</emphasis>.
+This means that when a person interacts with the system in different ways (assuming different roles) he will be
+represented by several actors. For example a person that gives customer support by the telephone and takes
+orders from the customer into the system would be represented by an actor <quote>Support Staff</quote> and
+an actor <quote>Sales Representative</quote>
+</para>
+</sect3>
+<sect3 id="use-case-description">
+<title>Use Case Description</title>
+<para>  <!-- FIXME this are not defined by UML. -->
+Use Case Descriptions are textual narratives of the Use Case. They usually take the form of a note or
+a document that is somehow linked to the Use Case, and explains the processes or activities that take
+place in the Use Case.
+</para>
+</sect3>
+</sect2> <!-- use-case-diagram -->
+
+<sect2 id="class-diagram">
+<title>Class Diagram</title>
+<para>
+Class Diagrams show the different classes that make up a system and how they relate to each other. Class Diagrams
+are said to be <quote>static</quote> diagrams because they show the classes, along with their methods and
+attributes as well as the static relationships between them: which classes <quote>know</quote> about which classes
+or which classes <quote>are part</quote> of another class, but do not show the method calls
+between them.
+</para>
+<para>
+<screenshot>
+<screeninfo>An example of a Class Diagram</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="class-diagram.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&umbrello; showing a Class Diagram</phrase>
+	  </textobject>
+	  <caption>
+	    <para>&umbrello; showing a Class Diagram
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+</para>
+<sect3 id="class">
+<title>Class</title>
+<para>
+A Class defines the attributes and the methods of a set of objects. All objects of this class (instances
+of this class) share the same behavior, and have the same set of attributes (each object has its own set).
+The term <quote>Type</quote> is sometimes used instead of Class, but it is important to mention that these
+two are not the same, and Type is a more general term.
+</para>
+<para>
+In &UML;, Classes are represented by rectangles, with the name of the class, and can also show
+the attributes and operations of the class in two other <quote>compartments</quote> inside the rectangle.
+</para>
+<para>
+<screenshot>
+<screeninfo>A Class in &UML;</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="class.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Visual representation of a Class in &UML;</phrase>
+	  </textobject>
+	  <caption>
+	    <para>Visual representation of a Class in &UML;
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+</para>
+<sect4 id="attribute">
+<title>Attributes</title>
+<para>
+In &UML;, Attributes are shown with at least their name, and can also show their type, initial value and
+other properties.
+Attributes can also be displayed with their visibility:
+</para>
+<itemizedlist>
+<listitem><para><literal>+</literal>  Stands for <emphasis>public</emphasis> attributes</para></listitem>
+<listitem><para><literal>#</literal>  Stands for <emphasis>protected</emphasis> attributes</para></listitem>
+<listitem><para><literal>-</literal>  Stands for <emphasis>private</emphasis> attributes</para></listitem>
+</itemizedlist>
+</sect4>
+<sect4 id="operation">
+<title>Operations</title>
+<para>
+Operations (methods) are also displayed with at least their name, and can also show their parameters and return
+types.
+Operations can, just as Attributes, display their visibility:
+<itemizedlist>
+<listitem><para><literal>+</literal>  Stands for <emphasis>public</emphasis> operations</para></listitem>
+<listitem><para><literal>#</literal>  Stands for <emphasis>protected</emphasis> operations</para></listitem>
+<listitem><para><literal>-</literal>  Stands for <emphasis>private</emphasis> operations</para></listitem>
+</itemizedlist>
+</para>
+</sect4>
+
+<sect4 id="templates">
+<title>Templates</title>
+<para>
+Classes can have templates, a value which is used for an unspecified class or type.  The template type is specified
+when a class is initiated (&ie; an object is created).  Templates exist in modern C++ and will be introduced in Java 1.5 where 
+they will be called Generics.
+</para>
+</sect4>
+</sect3>
+
+<sect3 id="class-associations">
+<title>Class Associations</title>
+<para>Classes can relate (be associated with) to each other in different ways:</para>
+<sect4 id="generalization">
+<title>Generalization</title>
+<para>Inheritance is one of the fundamental concepts of Object Orientated programming, in which a class
+<quote>gains</quote> all of the attributes and operations of the class it inherits from, and can
+override/modify some of them, as well as add more attributes and operations of its own.</para>
+<para>
+In &UML;, a <emphasis>Generalization</emphasis> association between two classes puts them in a hierarchy
+representing the concept of inheritance of a derived class from a base class. In &UML;, Generalizations are
+represented by a line connecting the two classes, with an arrow on the side of the base class.
+<screenshot>
+<screeninfo>Generalization</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="generalization.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Visual representation of a generalization in &UML;</phrase>
+	  </textobject>
+	  <caption>
+	    <para>Visual representation of a generalization in &UML;
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+</para>
+</sect4>
+
+<sect4 id="uml-associations">
+<title>Associations</title>
+<para>An association represents a relationship between classes, and gives the common semantics and structure
+for many types of <quote>connections</quote> between objects.</para>
+<para>Associations are the mechanism that allows objects to communicate to each other. It describes the connection
+between different classes (the connection between the actual objects is called object connection, or
+<emphasis>link</emphasis>.
+</para>
+<para>
+Associations can have a role that specifies the purpose of the association and can be uni- or bidirectional
+(indicates if the two objects participating in the relationship can send messages to the other, of if only
+one of them knows about the other). Each end of the association also has a multiplicity value, which dictates
+how many objects on this side of the association can relate to one object on the other side.
+</para>
+<para>
+In &UML;, associations are represented as lines connecting the classes participating in the relationship,
+and can also show the role and the multiplicity of each of the participants. Multiplicity is displayed as a
+range [min..max] of non-negative values, with a star (<literal>*</literal>) on the maximum side representing infinite.
+<screenshot>
+<screeninfo>&UML; Association</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="association.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Visual representation of an Association in &UML;</phrase>
+	  </textobject>
+	  <caption>
+	    <para>Visual representation of an Association in &UML;
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+</para>
+</sect4>
+
+<sect4 id="aggregation">
+<title>Aggregation</title>
+<para>Aggregations are a special type of associations in which the two participating classes don't have
+an equal status, but make a <quote>whole-part</quote> relationship. An Aggregation describes how the class
+that takes the role of the whole, is composed (has) of other classes, which take the role of the parts.
+For Aggregations, the class acting as the whole always has a multiplicity of one.
+</para>
+<para>
+In &UML;, Aggregations are represented by an association that shows a rhomb on the side of the whole.
+<screenshot>
+<screeninfo>Aggregation</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="aggregation.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Visual representation of an Aggregation relationship in &UML;</phrase>
+	  </textobject>
+	  <caption>
+	    <para>Visual representation of an Aggregation relationship in &UML;
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+</para>
+</sect4>
+<sect4 id="composition">
+<title>Composition</title>
+<para>Compositions are associations that represent <emphasis>very strong</emphasis> aggregations. This means,
+Compositions form whole-part relationships as well, but the relationship is so strong that the parts cannot
+exist on its own. They exist only inside the whole, and if the whole is destroyed the parts die too.</para>
+<para>In &UML;, Compositions are represented by a solid rhomb on the side of the whole.
+</para>
+<para><screenshot>
+<screeninfo>Composition</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="composition.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Visual representation of a Composition relationship in &UML;</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot></para>
+</sect4>
+</sect3> <!--class-associations-->
+
+<sect3 id="other-class-diagram-items">
+<title>Other Class Diagram Items</title>
+<para>Class diagrams can contain several other items besides classes.</para>
+<sect4 id="interfaces">
+<title>Interfaces</title>
+<para>Interfaces are abstract classes which means instances can not be directly created of them.  They can contain operations but no attributes.  Classes can inherit from interfaces (through a realisation association) and instances can then be made of these diagrams.</para>
+<!-- FIXME screenshot -->
+</sect4>
+<sect4 id="datatype">
+<title>Datatypes</title>
+<para>Datatypes are primitives which are typically built into a programming language.  Common examples include integers and booleans.  
+They can not have relationships to classes but classes can have relationships to them.</para>
+<!-- FIXME screenshot -->
+</sect4>
+<sect4 id="enum">
+<title>Enums</title>
+<para>Enums are a simple list of values.  A typical example is an enum for days of the week.  The options of an enum are called Enum Literals.
+Like datatypes they can not have relationships to classes but classes can have relationships to them.</para>
+<!-- FIXME screenshot -->
+</sect4>
+<sect4 id="package">
+<title>Packages</title>
+<para>Packages represent a namespace in a programming language.  In a diagram 
+they are used to represent parts of a system which contain more than one class, maybe hundereds of classes.</para>
+<!-- FIXME screenshot -->
+</sect4>
+</sect3>
+
+</sect2> <!-- class diagram -->
+
+<sect2 id="sequence-diagram">
+<title>Sequence Diagrams</title>
+
+<para> Sequence Diagrams show the message exchange (&ie; method call)
+between several Objects in a specific time-delimited
+situation. Objects are instances of classes.
+Sequence Diagrams put special emphasis in the order and the
+times in which the messages to the objects are sent.</para>
+
+<para> 
+In Sequence Diagrams objects are represented through vertical dashed lines, with the name of the Object
+on the top. The time axis is also vertical, increasing downwards, so that messages are sent from one Object
+to another in the form of arrows with the operation and parameters name. 
+</para>
+
+<!-- FIXME update screenshot to show synchronous messages -->
+<screenshot>
+<screeninfo>Sequence Diagram</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="sequence-diagram.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&umbrello; showing a Sequence Diagram</phrase>
+	  </textobject>
+	  <caption>
+	    <para>&umbrello; showing a Sequence Diagram
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+
+<para>Messages can be either synchronous, the normal type of message call where control is passed to the called object until that
+method has finished running, or asynchronous where control is passed back directly to the calling object.  Synchronous messages have
+a vertical box on the side of the called object to show the flow of program control.</para>
+</sect2> <!-- sequence diagrams -->
+
+<sect2 id="collaboration-diagram">
+<title>Collaboration Diagrams</title>
+
+<para>Collaboration Diagrams show the interactions occurring between the objects participating in a specific
+situation. This is more or less the same information shown by Sequence Diagrams but there the emphasis is
+put on how the interactions occur in time while the Collaboration Diagrams 
+put the relationships between the objects and their topology in the foreground.</para>
+
+<para>In Collaboration Diagrams messages sent from one object to another are represented by arrows, showing
+the message name, parameters, and the sequence of the message. Collaboration Diagrams are specially well suited
+to showing a specific program flow or situation and are one of the best diagram types to quickly demonstrate
+or explain one process in the program logic.
+</para>
+
+<screenshot>
+<screeninfo>Collaboration</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="collaboration-diagram.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&umbrello; showing a Collaboration Diagram</phrase>
+	  </textobject>
+	  <caption>
+	    <para>&umbrello; showing a Collaboration Diagram
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+
+</sect2> <!-- collaboration diagrams -->
+
+<sect2 id="state-diagram">
+<title>State Diagram</title>
+<para>State Diagrams show the different states of an Object during its life and the stimuli that
+cause the Object to change its state.
+</para>                              
+<para>State Diagrams view Objects as <emphasis>state machines</emphasis> or finite automates that can
+be in one of a set of finite states and that can change its state via one of a finite set of stimuli. For example
+an Object of type <emphasis>NetServer</emphasis> can be in one of following states during its life:
+</para>
+<itemizedlist>
+<listitem><para>Ready</para></listitem>
+<listitem><para>Listening</para></listitem>
+<listitem><para>Working</para></listitem>
+<listitem><para>Stopped</para></listitem>
+</itemizedlist>
+<para>and the events that can cause the Object to change states are</para>
+<itemizedlist>
+<listitem><para>Object is created</para></listitem>
+<listitem><para>Object receives message listen</para></listitem>
+<listitem><para>A Client requests a connection over the network</para></listitem>
+<listitem><para>A Client terminates a request</para></listitem>
+<listitem><para>The request is executed and terminated</para></listitem>
+<listitem><para>Object receives message stop</para></listitem>
+<listitem><para>etc</para></listitem>
+</itemizedlist>
+<para>
+<screenshot>
+<screeninfo>State Diagram</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="state-diagram.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&umbrello; showing a State Diagram</phrase>
+	  </textobject>
+	  <caption>
+	    <para>&umbrello; showing a State Diagram
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+</para>
+<sect3 id="state">
+<title>State</title>
+<para>States are the building block of State Diagrams. A State belongs to exactly one class and represents
+a summary of the values the attributes of a class can take. A &UML; State describes the internal state of an 
+object of one particular class
+</para>                       
+<para>Note that not every change in one of the attributes of an object should be represented by a State
+but only those changes that can significantly affect the workings of the object</para>
+<para> 
+There are two special types of States: Start and End. They are special in that there is no event that 
+can cause an Object to return to its Start state, in the same way as there is no event that can possible take
+an Object out of its End state once it has reached it.
+</para>
+</sect3>
+
+</sect2> <!-- state diagrams -->
+
+<sect2 id="activity-diagram">
+<title>Activity Diagram</title>
+<para>Activity Diagrams describe the sequence of activities in a system with the
+help of Activities. Activity Diagrams are a special form of State Diagrams, that only (or mostly) contains
+Activities.
+</para>
+<para>
+<screenshot>
+<screeninfo>An example Activity Diagram.</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="activity-diagram.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&umbrello; showing an Activity Diagram</phrase>
+	  </textobject>
+	  <caption>
+	    <para>&umbrello; showing an Activity Diagram
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+</para>
+<para>Activity Diagrams are similar to procedural Flux Diagrams, with the difference that all Activities
+are clearly attached to Objects.</para>
+
+<para>Activity Diagrams are always associated to a
+<emphasis>Class</emphasis>, an <emphasis>Operation</emphasis> or a
+<emphasis>Use Case</emphasis>.</para>
+
+<para>Activity Diagrams support sequential as well as parallel Activities. Parallel execution is represented
+via Fork/Wait icons, and for the Activities running
+in parallel, it is not important the order in which they are carried out (they can be executed at the same
+time or one after the other)</para>
+<sect3 id="activity">
+<title>Activity</title>
+<para>An Activity is a single step in a process. One Activity is one state
+in the system with internal activity and, at least, one outgoing transition. Activities can also have
+more than one outgoing transition if they have different conditions.
+</para> 
+<para>Activities can form hierarchies, this means that an Activity can be composed of several <quote>detail</quote>
+Activities, in which case the incoming and outgoing transitions should match the incoming and outgoing transitions
+of the detail diagram.
+</para>
+
+</sect3>
+</sect2> <!-- activity diagram -->
+
+<sect2 id="helper-elements">
+<title>Helper Elements</title>
+<para>There are a few elements in &UML; that have no real semantic value for the model, but help to clarify
+parts of the diagram. These elements are </para>
+<itemizedlist>
+<listitem><para>Text lines</para></listitem>
+<listitem><para>Text Notes and anchors</para></listitem>
+<listitem><para>Boxes</para></listitem>
+</itemizedlist>   
+<para>
+Text lines are useful to add short text information to a diagram. It is free-standing text and has no 
+meaning to the Model itself.
+</para>           
+
+<para> 
+Notes are useful to add more detailed information about an
+object or a specific situation. They have the great advantage that
+notes can be anchored to &UML; Elements to show that the note
+<quote>belongs</quote> to a specific object or situation.  
+</para>
+
+<para>Boxes are free-standing rectangles which can be used to group items together to make diagrams more readable.  They
+have no logical meaning in the model.</para>
+
+<!-- FIXME, screenshot -->
+</sect2> <!-- helper elements -->
+
+<sect2 id="component-diagram">
+<title>Component Diagrams</title>
+<para>Component Diagrams show the software components (either component technologies such as KParts, CORBA components or Java Beans or 
+just sections of the system which are clearly distinguishable) and the artifacts they
+are made out of such as source code files, programming libraries or relational database tables.</para>
+
+<para>Components can have interfaces (&ie; abstract classes with operations) that allow associations between components.</para>
+</sect2>
+
+<sect2 id="deployment-diagram">
+<title>Deployment Diagrams</title>
+
+<para>Deployment diagrams show the runtime component instances and their
+associations.  They include Nodes which are physical resources,
+typically a single computer.  They also show interfaces and objects (class instances).</para>
+
+</sect2>
+
+</sect1> 
+</chapter>
diff --git a/doc/umbrello/use-case-diagram.png b/doc/umbrello/use-case-diagram.png
new file mode 100644
index 00000000..36f4320d
--- /dev/null
+++ b/doc/umbrello/use-case-diagram.png
diff --git a/doc/umbrello/working_with_umbrello.docbook b/doc/umbrello/working_with_umbrello.docbook
new file mode 100644
index 00000000..3cf32f83
--- /dev/null
+++ b/doc/umbrello/working_with_umbrello.docbook
@@ -0,0 +1,448 @@
+<chapter id="working-with-umbrello">
+<title>Working with &umbrello;</title>
+<!-- Umbrello basics: creating diagrams, creating classes, adding objects to diagrams,
+   associations, editing properties, anchor points in associations, removing objects, removing
+   diagrams
+-->
+
+<para>
+This chapter will introduce you to &umbrello;'s user interface and will
+tell you all you need to know to start modelling.  All actions in &umbrello; are accessible via the menu and
+the toolbars, but &umbrello; also makes extensive use of &RMB; context menus. You can &RMB; click on almost any element in
+&umbrello;'s work area or tree view to get a menu with the most useful
+functions that can be applied to the particular element you are
+working on. Some users find this a little confusing at the beginning because they are more used to working with the menu or tool bars, but
+once you get used to <mousebutton>right</mousebutton> clicking it will greatly speed up your work.
+</para>
+
+<sect1 id="user-interface">
+<title>User Interface</title>
+<para>
+&umbrello;'s main window is divided in three areas that will help you keep an overview of your entire system
+and access the different diagrams quickly while working on your model.
+</para>
+<para>These areas are called:</para>
+<itemizedlist>
+<listitem><para>Tree View</para></listitem>
+<listitem><para>Work Area</para></listitem>
+<listitem><para>Documentation Window</para></listitem>
+</itemizedlist>
+
+<screenshot>
+<screeninfo>&umbrello;'s User Interface</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="umbrello-ui.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>&umbrello;'s User Interface</phrase>
+	  </textobject>
+	  <caption>
+	    <para>&umbrello;'s User Interface
+	    </para>
+	  </caption>
+	</mediaobject>
+</screenshot>
+
+<sect2 id="tree-view">
+<title>Tree View</title>
+<para>
+The Tree View is usually located on the top left hand side of the window and shows the all the diagrams,
+classes, actors and use cases that build up your model.
+The Tree View allows you to have a quick overview of the elements composing your model. The Tree View also
+gives you a quick way to switch between the different diagrams in your model and inserting elements from
+your model into the current diagram.
+</para>
+<para>
+If you are working on a model with more than just a few classes and diagrams, the Tree View may help
+you stay on top of things by organizing your model elements in folders. You can create 
+folders by selecting the appropriate option from the context menu (&RMB; click on one of the folders
+in the tree view) and you can organize your elements by moving them to the appropriate folder (drag and drop)
+<!-- (screen shot) FIXME-->
+</para>
+</sect2>
+
+<sect2 id="documentation-window">
+<title>Documentation Window</title>
+<para>
+The Documentation Window is the small window located on the left bottom of &umbrello;, and it gives
+you a quick preview of the documentation for the currently selected item. The Documentation Window is
+rather small because it is intended to allow you just a quick pick into the element's documentation while
+taking as little screen space as possible. If you need to view the documentation in more detail you can always
+open the item's properties.
+</para>
+</sect2>
+<sect2 id="work-area">
+<title>Work Area</title>
+<para>
+The Work Area is the main window in &umbrello; and is where the real action takes place. You use the Work Area
+to edit and view the diagrams in your model. The Work Area shows the currently active diagram.  Currently
+only one diagram can be shown on the Work Area at any time.
+</para>
+</sect2>
+</sect1> <!--user-interface-->
+<sect1 id="load-save">
+<title>Creating, Loading and Saving Models</title>
+<para>
+The first thing you need to start doing something useful with &umbrello; is to create a model to work on.
+When you start &umbrello; it always loads the last used model or creates a new, empty model (depending on
+your preferences set in the configuration dialog). This will allow you to start working right away.
+</para>
+<sect2 id="new-model">
+<title>New Model</title>
+<para>
+If at any time you need to create a new model you can do this by selecting the <guimenuitem>New</guimenuitem> entry from the
+<guimenu>File</guimenu> menu, or by clicking on the <guiicon>New</guiicon> icon from the application toolbar. If you are currently working on
+a model which has been modified &umbrello; will ask you if it should save your changes before loading the
+new model.
+</para>
+</sect2>
+<sect2 id="save-model">
+<title>Save Model</title>
+<para>
+You can save your model at any time by selecting the option <guimenuitem>Save</guimenuitem> from the <guimenu>File</guimenu> Menu or by clicking
+on the <guiicon>Save</guiicon> button from the application toolbar. If you need to save your model under a different name
+you can use the option <guimenuitem>Save As</guimenuitem> from the <guimenu>File</guimenu> Menu.
+</para>
+<para>For your convenience &umbrello; also offers you the option to automatically save your work
+each certain time period. You can configure if you want this option as well as the time intervals
+in the <guimenu>Settings</guimenu> from &umbrello;</para>
+</sect2>
+<sect2 id="load-model">
+<title>Load Model</title>
+<para>
+For loading an already existing model you may select the option <guimenuitem>Open</guimenuitem> from the <guimenu>File</guimenu> Menu or click on the <guiicon>Open</guiicon>
+icon from the application toolbar. The most recently used models are also available under the submenu
+<guimenuitem>Open Recent</guimenuitem> in the <guimenu>File</guimenu> Menu to speed up access to your most frequently used models.
+</para>
+<para>
+&umbrello; can only work on one model at a time, so if you ask the program to load a model for you and your
+current model has been modified since the last time you save it, &umbrello; will ask you whether your changes
+should be saved to prevent any loss of work.  You can start two or more instances of &umbrello; at any one time, you can also copy and paste between instances.
+</para>
+</sect2>
+</sect1>  <!--load-save-->
+<sect1 id="edit-model">
+<title>Editing Models</title>
+<para>
+In &umbrello;, there are basically two ways for editing the elements in your model.
+<itemizedlist>
+<listitem><para>Edit model elements directly through the Tree View</para></listitem>
+<listitem><para>Edit model elements through a Diagram</para></listitem>
+</itemizedlist>
+</para>
+<para>
+Using the context menu of the different items in the Tree View you are able to add, remove, 
+and modify almost all the elements in your model. <mousebutton>Right</mousebutton> clicking on the folders in the Tree View
+will give you options for creating the different types of diagrams as well as, depending on whether
+the folder is a <emphasis>Use Case View</emphasis> or a <emphasis>Logical View</emphasis>, Actors,
+Use Cases, Classes, etc.
+</para>
+<para>
+Once you have added elements to your model you can also edit an element by accessing its properties
+dialog, which you find by selecting the option <emphasis>Properties</emphasis> from the context menu
+shown when <mousebutton>right</mousebutton> clicking on the items in the Tree View.
+</para>
+<para>
+You can also edit your model by creating or modifying elements through diagrams. More details on how
+to do this are given in the following sections.
+</para>
+</sect1>
+<sect1 id="add-remove-diagrams">
+<title>Adding and Removing Diagrams</title>
+<para>
+Your &UML; model consists of a set of &UML; elements and associations between them. However you cannot see the model
+directly, you use <emphasis>Diagrams</emphasis> to look at it.
+</para>
+<sect2 id="create-diagram">
+<title>Creating Diagrams</title>
+<para>
+To create a new diagram in your model simply select the diagram type you need from the <guimenuitem>New</guimenuitem> submenu in the <guimenu>Diagram</guimenu> menu and give a name to it. The diagram will be created and made active, and you will immediately
+see it in the tree view.
+</para>
+<para>
+Remember that &umbrello; makes extensive use of context menus: you can also &RMB; click on a folder in the Tree
+View and select the appropriate diagram type from the <guisubmenu>New</guisubmenu> submenu in the context menu. Note that you can create
+Use Case Diagrams only in Use Case View folders, and the other types of diagram can only be created in the
+Logical View folders.
+</para>
+</sect2>
+<sect2 id="remove-diagram">
+<title>Removing Diagrams</title>
+<para>
+Should you need to remove a diagram from your model, you can do this by making it active and selecting
+<guimenuitem>Delete</guimenuitem> from the <guimenu>Diagram</guimenu> Menu. You can also achieve this by selecting <guimenuitem>Delete</guimenuitem> from the diagrams context menu
+in the Tree View
+</para>
+<para>Since deleting a diagram is something serious that could cause loss of work if done by accident, &umbrello;
+will ask you to confirm the delete operation before actually removing the Diagram. Once a diagram has been
+deleted and the file has been saved there is no way to undo this action.
+</para>
+</sect2>
+<sect2 id="rename-diagram">
+<title>Renaming Diagrams</title>
+<para>
+If you want to change the name of an existing diagram you can easily do this by selecting the Rename option
+from its &RMB; menu in the Tree View.
+</para>
+<para>Another way to rename a diagram is to do this via its properties dialog, which you obtain by
+selecting Properties from its Context Menu or by double clicking on it in the Tree View.
+</para>
+</sect2>
+</sect1>
+<sect1 id="edit-diagram">
+<title>Editing Diagrams</title>
+<para>
+When working on a diagram, &umbrello; will try to guide you by applying some simple rules as to which
+elements are valid in the different types of diagrams, as well as the relationships that can exist
+between them. If you are an &UML; expert you will probably not even notice it, but this will help
+&UML; novices create standard-conformant diagrams.
+</para>
+<para>
+Once you have created your diagrams it is time to start editing them. Here you should notice 
+the (for beginners subtle) difference between editing your diagram, and editing the
+<emphasis>model</emphasis>. As you already know, Diagrams are <emphasis>views</emphasis> of your model.
+For example, if you create a class by editing a Class Diagram, you are really editing both, your
+Diagram and your model. If you change the color or other display options of a Class in your Class
+Diagram, you are only editing the Diagram, but nothing is changed in your model.
+</para>
+<sect2 id="insert-elements">
+<title>Insert Elements</title>
+<para>
+One of the first things you will do when editing a new diagram is to insert elements into them (Classes,
+Actors, Use Cases, &etc;) There is basically two ways of doing this:</para>
+<itemizedlist>
+<listitem><para>Dragging existing elements in your model from the Tree View</para></listitem>
+<listitem><para>Creating new elements in your model and adding them to your diagram at the
+same time, by using one of the edit Tools in the Work Toolbar</para></listitem>
+</itemizedlist>
+<para>
+To insert elements that already exist in your model, just drag them from the Tree View and
+drop them where you want them to be in your diagram. You can always move elements around
+in your Diagram using the Select Tool
+</para>
+<para>
+The second way of adding elements to your diagram is by using the Work Toolbar's edit tools (note
+that this will also add the elements to your model).
+</para>
+<para>
+The Work Toolbar was by default located on the far right of the application window, &umbrello; 1.2 has moved this to the top of the window.
+You can dock it into other edge or have it floating around if you prefer. The tools available
+on this toolbar (the buttons you see on it) change depending on the type of diagram
+you are currently working on. The button for the currently
+selected tool is activated in the toolbar. You can switch to the select tool
+by pressing the &Esc; key.
+</para>
+<para>
+When you have selected an edit tool from the Work Toolbar (for example, the tool to insert classes)
+the mouse pointer changes to a cross, and you can insert the elements in your model by single clicking
+in your diagram. Note that elements in &UML; must have a <emphasis>Unique Name</emphasis>. So that if
+you have a class in one diagram whose name is <quote>ClassA</quote> and then you use the insert Class
+tool to insert a class into another diagram you cannot name this new class <quote>ClassA</quote> as well.
+If these two are supposed to be two different elements, you have to give them a unique name. If you are
+trying to add the <emphasis>same</emphasis> element to your diagram, then the Insert Class is not
+the right tool for that. You should drag and drop the class from the Tree View instead.
+</para>
+</sect2>
+<sect2 id="delete-elements">
+<title>Deleting Elements</title>
+<para>
+You can delete any element by selecting the option <guimenuitem>Delete</guimenuitem> from its context menu.
+</para>
+<para>
+Again, there is a <emphasis>big</emphasis> difference between removing an object from a diagram, and
+deleting an object from your model:
+If you delete an object from within a diagram, you are only removing the object from that particular
+diagram: the element will still be part of your model and if there are other diagrams using the same
+element they will not suffer any change.
+If, on the other hand, you delete the element from the Tree View, you are actually deleting the
+element from your <emphasis>model</emphasis>. Since the element no longer exist in your model,
+it will be automatically removed from all the diagrams it appears in.
+</para>
+</sect2>
+<sect2 id="edit-elements">
+<title>Editing Elements</title>
+<para>
+You can edit most of the &UML; elements in your model and diagrams by opening its Properties dialog
+and selecting the appropriate options.
+To edit the properties of an object, select <guimenuitem>Properties</guimenuitem> from its context menu (&RMB; click). Each element has a dialog consisting of several pages where you can configure the options
+corresponding to that element. For some elements, like actors you can only set a couple of options,
+like the object name and documentation, while for other elements, like classes, you can edit its
+attributes and operations, select what you want to be shown in the diagram (whole operation signature
+or just operation names, etc) and even the colors you want to use for the line and fill of the class'
+representation on the diagram.
+</para>
+
+<para>
+For most &UML; elements you can also open the properties dialog by
+double clicking on it if you are using the selection tool (arrow). The
+exception to this is Associations, in which case a double click
+creates an anchor point. For associations you need to use the &RMB; context menu to get the properties dialog.
+</para>
+
+<para>
+Note that you can also select the properties option from the context
+menu of the elements in the Tree View. This allows you to also edit
+the properties for the diagrams, like setting whether the grid should
+be shown or not.
+</para>
+</sect2>
+<sect2 id="edit-classes">
+<title>Editing Classes</title>
+<para>
+Even though editing the properties of all objects was already covered in the previous section,
+classes deserve a special section because they are a bit more complicated and have more options
+than most of the other &UML; elements.
+</para>
+<para>
+In the properties dialog for a class you can set everything, from the color it uses to the operations
+and attributes it has.
+</para>
+<sect3 id="class-general-settings">
+<title>Class General Settings</title>
+<para>
+The General Settings page of the properties dialog is self-explanatory. Here you can change the
+class' name, visibility, documentation, &etc;
+This page is always available.
+</para>
+</sect3>
+<sect3 id="class-attributes-settings">
+<title>Class Attribute Settings</title>
+<para>
+In the Attributes Settings page you can add, edit, or delete attributes (variables) of the class.
+You can move attributes up and down the list by pressing the arrow button
+on the side.
+This page is always available.
+</para>
+</sect3>
+<sect3 id="class-operations-settings">
+<title>Class Operations Settings</title>
+<para>
+Similar to the Attribute Settings Page, in the Operation Settings Page you can add, edit, or
+remove operations for your class. When adding or editing an operation, you enter the basic data in
+the <emphasis>Operation Properties</emphasis> dialog. If you want to add parameters to your operation
+you need to click the <guibutton>New Parameter</guibutton> button, which will show the
+<emphasis>Parameter Properties</emphasis> dialog.
+This page is always available
+</para>
+</sect3>
+<sect3 id="class-template-settings">
+<title>Class Template Settings</title>
+<para>
+This page allows you to add class templates which are unspecified classes or datatypes.  In Java 1.5 these will be called Generics.
+</para>
+</sect3>
+<sect3 id="class-associations-page">
+<title>Class Associations Page</title>
+<para>
+The <guilabel>Class Associations</guilabel> page shows all the associations of this class
+in the current diagram. Double clicking on an association shows its properties, and depending
+on the type of association you may modify some parameters here such as setting multiplicity and Role
+name. If the association does not allow such options be be modified, the Association Properties dialog
+is read-only and you can only modify the documentation associated with this association.
+</para>
+<para>
+This page is only available if you open the Class Properties from within a diagram. If you select
+the class properties from the context menu in the Tree View this page is not available.
+</para>
+</sect3>
+<sect3 id="class-display-page">
+<title>Class Display Page</title>
+<para>
+In the <guilabel>Display Options</guilabel> page, you can set what is to be shown in the diagram.
+A class can be shown as only one rectangle with the class name in it (useful if you have many
+classes in your diagram, or are for the moment not interested in the details of each class) or
+as complete as showing packages, stereotypes, and attributes and operations with full signature and
+visibility
+</para>
+<para>Depending on the amount of information you want to see you can select the corresponding
+options in this page. The changes you make here are only <emphasis>display options</emphasis>
+for the diagram. This means that <quote>hiding</quote> a class' operations only makes them
+not to be shown in the diagram, but the operation are still there as part of your model.
+This option is only available if you select the class properties from within a Diagram. If you open
+the class properties from the Tree View this page is missing since such Display Options do not make sense
+in that case</para>
+</sect3>
+<sect3 id="class-color-page">
+<title>Class Color Page</title>
+<para>
+In the <guilabel>Widget Color</guilabel> page you can configure the colors you want for the line
+and the fill of the widget. This option obviously makes sense only for classes displayed in diagrams,
+and is missing if you open the class' properties dialog from the Tree View.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="associations">
+<title>Associations</title>
+<para>
+Associations relate two &UML; objects to each other. Normally associations are defined between two classes,
+but some types of associations can also exists between use cases and actors.
+</para>
+<para>
+To create an association select the appropriate tool from the Work Toolbar (generic Association,
+Generalization, Aggregation, &etc;) and single click on the first element participating in the association
+and then single click on the second item participating. Note that those are two clicks, one on each
+on the objects participating in the association, it is <emphasis>not</emphasis> a drag from one object
+to the other. <!-- yet :) -->
+</para>
+<para>
+If you try to use an association in a way against the &UML; specification &umbrello; will refuse to create
+the association and you will get an error message. This would be the case if, for example, a Generalization
+exists from class A to class B and then you try to create another Generalization from Class B to class A
+</para>
+<para>
+<mousebutton>Right</mousebutton> clicking on an association will show a context menu with the actions you can apply on it. If you need to delete an association simply select the <guimenuitem>Delete</guimenuitem> option from this context menu.
+You can also select the <guimenuitem>Properties</guimenuitem> option and, depending on the association type
+edit attributes such as roles and multiplicity.
+</para>
+<sect3 id="anchor-points">
+<title>Anchor Points</title>
+<para>
+Associations are drawn, by default, as a straight line connecting the two objects in the diagram. 
+</para>
+<para>
+You can add anchor points to bend an association by <mousebutton>double</mousebutton> clicking some where along the association line. This will insert
+an anchor point (displayed as a blue point when the association line is selected) which you can move
+around to give shape to the association
+</para>
+<para>
+If you need to remove an anchor point, <mousebutton>double</mousebutton> click on it again to remove it
+</para>
+<para>
+Note that the only way to edit the properties of an association is through the context menu. If you
+try to <mousebutton>double</mousebutton> click on it as with other &UML; objects, this will only insert an anchor point.
+</para>
+</sect3>
+</sect2>
+
+<sect2 id="notes">
+<title>Notes, Text and Boxes</title>
+<para>
+Notes, Lines Of Text and Boxes are elements that can be present in any type of diagram and have no real
+semantic value, but are very helpful to add extra comments or explanations that can make your
+diagram easier to understand.
+</para>
+<para>
+To add a Note or a Line Of Text, select the corresponding tool from the Work Toolbar and single click
+on the diagram where you want to put your comment. You can edit the text by opening the element through
+its context menu or in the case of notes by <mousebutton>double</mousebutton> clicking on them as well.
+</para>
+<sect3 id="anchors">
+<title>Anchors</title>
+<para>
+Anchors are used to link a text note and another &UML; Element together. For example, you normally
+use a text note to explain or make some comment about a class or a particular association, in which
+case you can use the anchor to make it clear that the note <quote>belongs</quote> to that particular
+element.
+</para>
+<para>
+To add an anchor between a note and another &UML; element, use the anchor tool from the work toolbar.
+You first need to click on the note and then click on the &UML; element you want the note to be linked
+to.
+</para>
+</sect3>
+</sect2>
+</sect1>
+</chapter>
+<!--edit-diagram-->