<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1.2-Based Variant V1.0//EN" "dtd/kdex.dtd" [
  <!ENTITY kig "<application>Kig</application>">
  <!ENTITY kseg "<application>KSeg</application>">
  <!ENTITY cabri "<application>Cabri</application>">
  <!ENTITY package "kdeedu">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE"><!-- change language only here -->
]>

<book lang="&language;">

  <bookinfo>
    <title>The &kig; Handbook</title>

    <authorgroup>
      <author>
	<firstname>Dominique</firstname> <surname>Devriese</surname>
	<affiliation>
	  <address><email>devriese@kde.org</email></address>
	</affiliation>
      </author>
    </authorgroup>

    <!-- TRANS:ROLES_OF_TRANSLATORS -->

    <copyright>
      <year>2002-2003</year> <holder>Dominique Devriese</holder>
    </copyright>

    <legalnotice>&FDLNotice;</legalnotice>

    <date>2003-04-5</date> <releaseinfo>0.4.0</releaseinfo>
    
    <abstract>
      <para>
	&kig; is a &kde; application for Interactive Geometry.  It is
	meant as a replacement for the free programs &kgeo; and
	&kseg;, and for commercial applications like &cabri;
      </para>
    </abstract>

    <keywordset>
      <keyword>KDE</keyword> <keyword>KDE-Edu</keyword>
      <keyword>Kig</keyword> <keyword>Interactive Geometry</keyword>
      <keyword>KGeo</keyword> <keyword>Cabri</keyword>
    </keywordset>
  </bookinfo>

  <chapter id="introduction">
    <title>Introduction</title>

    <para>
      &kig; is an application for Interactive Geometry. It's intended
      to serve two purposes:
    </para>

    <itemizedlist>
      <listitem><para> Allow students to interactively explore
      mathematical figures and concepts using the computer.
      </para></listitem>

      <listitem><para> Serve as a <acronym>WYSIWYG</acronym> tool for
      drawing mathematical figures and including them in other
      documents.</para></listitem>
    </itemizedlist>

    <para>
      You can report problems in &kig; using the internal bug
      reporting tool
      (<menuchoice><guimenu>Help</guimenu><guimenuitem>Report
      Bug</guimenuitem></menuchoice>), or just contact me at
      <email>devriese@kde.org</email>.
    </para>
    <para>
      Since &kig; supports macros and locuses, it allows for some
      rather advanced macros to be defined.  If you have created an
      interesting macro, that you think might be useful for other
      people, you can mail it to me at <email>devriese@kde.org</email>, so I can include it in
      the distribution ( if you do this, it will be licensed under the
      terms of &kig;'s license, the <ulink url="http://www.gnu.org/licenses/licenses.html#GPL">GPL</ulink>, so that other people can
      freely use and adapt it ).
    </para>
  </chapter>
  
  <chapter id="using-kig-basic">
    <title>Basic usage</title>
    <section id="constructing-objects">
      <title>Constructing Objects</title>
      <section id="constructing-points">
	<title>Constructing points</title>
	<para>
	  You can construct points in several ways:
	  <itemizedlist>
	    <listitem>
	      <para>
		Select <menuchoice><guimenu>Objects</guimenu>
		<guisubmenu>Points</guisubmenu><guimenuitem> Normal
		Point</guimenuitem></menuchoice> from the menu bar or
		press the appropriate button in the toolbar.  You can
		then construct a point by clicking on the desired
		position in the window.  <note><para>Actually, this
		works the same way for constructing other objects as
		well: click on the desired menu bar entry or toolbar
		button and select the necessary objects to construct
		the object.</para></note>
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Since you often need to construct points, simply clicking
		somewhere on the screen with the
    <mousebutton>middle</mousebutton> mouse button will construct a
    point for you, without going to a menu or button.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		You can construct points while you are
		building other objects in the background, optionally selecting them
		for the object you are building.  For more on this,
    see the <link linkend="constructing-other-objects">section below</link>.
	      </para>
	    </listitem>
	  </itemizedlist>
	</para>
	<screenshot>
	  <screeninfo>A point has been constructed</screeninfo>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="constructed_a_point.png"
	      format="PNG"/>
	    </imageobject>
	    <textobject>
	      <phrase>A point has been constructed</phrase>
	    </textobject>
	  </mediaobject>
	</screenshot>
      </section>

      <section id="constructing-other-objects">
	<title>Constructing Other Objects</title>
	<para>
	  Constructing objects other than points is normally done by
	  selecting the appropriate entry in the
	  <guimenu>Objects</guimenu> menu, or by clicking on one of the
	   toolbar buttons.
	</para>
	<screenshot>
	  <screeninfo>Constructing a circle</screeninfo>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="constructing_a_circle.png"
	      format="PNG"/>
	    </imageobject>
	    <textobject>
	      <phrase>Constructing a circle</phrase>
	    </textobject>
	  </mediaobject>
	</screenshot>
	<para>
	  This will start the construction of the chosen object type.
  All of these types require arguments.  For
	  example, if you selected a circle by center and point, you
	  will need to give it two points: one for the center, and one
	  for the point on the circle.
	</para>
	<para>
	  To select these arguments, simply click on
	  the object you want to use.  If you move over an object that
	  can be used to construct the object, a preliminary image
	  will be shown of what the object will look like.  For
	  objects that require points as arguments, you can construct
	  a new point at the current cursor position and select it by
	  clicking the <mousebutton>left</mousebutton> mousebutton.
	</para>
	<para>
	  You can always cancel the construction of the new object by
	  pressing the <keycap>Escape</keycap> button or by clicking
	on the "Stop" button (red octagon with an 'X') on the toolbar.
	</para>
	<screenshot>
	  <screeninfo>Constructing a circle.</screeninfo>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="constructing_a_circle_2.png"
	      format="PNG"/>
	    </imageobject>
	    <textobject>
	      <phrase>Constructing a circle</phrase>
	    </textobject>
	  </mediaobject>
	</screenshot>
      </section>
    </section>

    <section id="selecting-objects">
      <title>Selecting Objects</title>
      <para>
	Selecting objects can be done in two ways:
      </para>
      <itemizedlist>
	<listitem>
	  <para>
	    Simply clicking on an object causes that object to be
      selected, clearing the current selection.  If you
	    don't want that behavior, hold down the &Ctrl; key while clicking on an
	    object.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    By clicking and dragging on an empty spot on the screen, you can
	    select all objects within the rectangle that is
      created. This action will clear the current selection.  As in the previous case, holding
	    down the &Ctrl; key prevents this behavior.
	  </para>
	</listitem>
      </itemizedlist>

      <screenshot>
	<screeninfo>Selecting objects</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="selecting_objects.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Selecting objects</phrase>
	  </textobject>
	</mediaobject>
      </screenshot>
    </section>

    <section id="moving-objects">
      <title>Moving Objects</title>
      <para>
	To move objects, you must first <link
	linkend="selecting-objects">select</link> them.
      </para>
      <para>
	When the objects you want to move are selected, you can start
	moving them by <mousebutton>left</mousebutton> clicking and
      dragging on any one of them.
  When you're done, simply release the left mouse button.
      </para>
      <note><para>For some types of objects ( mostly complicated
      Locuses ), moving objects can be slow on older hardware.  This
      is unfortunate, but inevitable, given the calculations
      involved.  </para></note> 
      <note><para>If you <mousebutton>right-</mousebutton>click one of
      the selected objects, and choose
      <menuchoice><guimenuitem>"move"</guimenuitem></menuchoice>,
      movement of the mouse will move the object. When the object is
      moved to the desired position, another
      <mousebutton>left</mousebutton> button click will stop the movement.  </para></note>
    </section>
    <section id="deleting-objects">
      <title>Deleting objects</title>
      <para>
	Deleting objects is done by first <link
	linkend="selecting-objects">selecting</link> them, and next
	doing either of these:
	<itemizedlist>
	  <listitem>
	    <para>
	      Press the <keycap>Delete</keycap> key.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Press the delete button on the toolbar.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      <mousebutton>Right-</mousebutton>click on one of the
	      objects, and select
	      <menuchoice><guimenuitem>Delete</guimenuitem></menuchoice>
	      in the <link linkend="objects-context-menus">context
	      menu</link> that appears.

	    </para>
	  </listitem>
	</itemizedlist>
      </para>
    </section>
    <section id="showing-hiding-objects">
      <title>Showing and hiding objects</title>
      <para>
	In &kig;, objects can be hidden.  This is done by selecting
	the objects, <mousebutton>right-</mousebutton>clicking one of
	them, and selecting
	<menuchoice><guimenuitem>Hide</guimenuitem></menuchoice> in
	the <link linkend="objects-context-menus">context menu</link>
	that appears..
      </para>
      <para>
	For unhiding the objects, use the
	<menuchoice><guimenu>Edit</guimenu><guimenuitem>Unhide
	all...</guimenuitem></menuchoice>.  This will unhide all
	currently hidden objects.
      </para>
    </section>
    <section id="undo-redo">
      <title>Undo/Redo</title>
      <para>
	In &kig;, you can undo almost any change you do to the
	document.  Just use the undo/redo buttons on the toolbar, or
	the appropriate shortcuts..
      </para>
    </section>
    <section id="full-screen-mode">
      <title>Full Screen Mode</title>
      <para>
	&kig; also has a Full Screen mode.  To use it, click the appropriate button on the toolbar, or
	select <menuchoice><guimenu>View</guimenu><guimenuitem>Full
	Screen</guimenuitem></menuchoice>.  
      </para>
      <para>
	To leave Full Screen mode,
	<mousebutton>Right</mousebutton>-click the screen on a place
	where there is no object present, and select
	<menuchoice><guimenuitem>Exit Full Screen Mode</guimenuitem>
	</menuchoice>, or press the <keycap>Escape</keycap> key.
      </para>
    </section>
  </chapter>

  <chapter id="using-advanced">
    <title>Advanced Usage</title>
    <section id="objects-context-menus">
      <title>Context Menus</title>
      <para>
	&kig; has context menus for its objects.  Try
	<mousebutton>right-</mousebutton>clicking on an object to see
a context menu appear.  There are many options: for constructing
	other objects, setting colors, and even hiding, moving or deleting
	objects.  Some objects have options of their own (
	e.g. you can redefine certain points to be constrained to a
	line where they previously weren't, etc ).  Try out these
    options for yourself ;). They should be very straightforward to understand.
      </para>
    </section>
    <section id="document-context-menus">
      <title>Document context menus</title>
      <para>
	 <mousebutton>Right-</mousebutton>clicking on the
	document will present a popup that you can use to
	start constructing a new object, change the coordinate system
	used, show hidden objects, and even zoom in and zoom out of the
	document.
      </para>
    </section>
    <section id="defining-macros">
      <title>Defining Macros</title>
      <para>
	One of the more advanced features in &kig; is its support for
	macros.  This allows you to define a new type of objects by
	combining other ones.
      </para>
      <para>
	For example:  Suppose you want
	to make a macro for constructing a circle from three points on
	it ( suppose you missed the fact that &kig; provides a native
	type for this purpose ;) ), then you would just construct
	three points, some perpendiculars and midpoints until you find
	the center, and construct the circle by the center you
	constructed and one of the previous points.  The following
	image should make this a bit more clear.
      </para>
      <screenshot>
	<screeninfo>Test running macros</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="test_run_macro.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Test running macros</phrase>
	  </textobject>
	</mediaobject>
      </screenshot>

      <para>
	Next comes defining the macro.  Select <guimenuitem>New
	macro</guimenuitem> from the <guimenu>Type</guimenu> menu, or
	click on the button on the toolbar.  A wizard will appear and ask
	you to select the given objects.  In our example, these are
	the three points.  Select the three points (click on
	them for selecting, click again for unselecting) and click the
	<guibutton>next</guibutton> button to continue. Finally, select
	the last objects ( only the circle in our example ).
      </para>

      <screenshot>
	<screeninfo>The macro wizard</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="macro_wizard.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>The macro wizard</phrase>
	  </textobject>
	</mediaobject>
      </screenshot>

      <para> After the previous steps were completed, click the
      <guibutton>next</guibutton> button to continue.  Enter a name and
      optionally a description for your new type, and click the
      <guibutton>Finish</guibutton> button.  Your macro type is now
      finished.
      </para>

      <para>
	To use the new macro type, click its button on the toolbar or
	use the <menuchoice><guimenu>Objects</guimenu></menuchoice> menu
	or even its button on the toolbar.  Building a macro object
	is just like constructing any other object.
      </para>
      <screenshot>
	<screeninfo>Using your new type</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="macros_at_work.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Using your new type</phrase>
	  </textobject>
	</mediaobject>
      </screenshot>
    </section>
    <section id="working-with-types">
      <title>Working with types</title>
      <para>
	As you saw in the previous chapter, &kig; allows you to create
	your own objects.  &kig; also makes sure that once you have
	created an object, it is saved on exit and loaded on startup.  
You do not have to manually save or load
	macro definitions.  However, &kig; does allow you to do more
	with the macros.  If you select <guimenuitem>Manage
	Types</guimenuitem> from the <guimenu>Types</guimenu>-menu,
	you will see a dialog where you can edit your types.  It
	allows you to delete types that are no longer used,
	export them to a file, or even load them from another file.
      </para>
      <screenshot>
	<screeninfo>Edit Types Dialog</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="edit_types_dialog.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>The Edit Types Dialog</phrase>
	  </textobject>
	</mediaobject>
      </screenshot>
    </section>
    <section id="text-labels">
      <title>Text labels</title>
      <para>
	&kig; allows you to add text labels to a construction.  This
	is very useful for showing names, explanations or other text in
	constructions.  &kig; can also display variable information about objects (
	a.k.a. properties ).
      </para>
      <para>
        To construct a text label, simply press the Text Label button
        in the Kig toolbar or select
        <menuchoice><guimenu>Objects</guimenu><guisubmenu>Other
        </guisubmenu><guimenuitem>Text label</guimenuitem>
        </menuchoice> in the menu bar.  Then click the screen on the
        place where you want to place the label.
      </para>
      <para>
        Type in the text that you want to show in the new label, and
	click "Finish". The label should be present on your document now.
      </para>
      <screenshot>
	<screeninfo>The Text Label Dialog</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="text_label_wizard.png" format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>The Text Label Dialog</phrase>
	  </textobject>
	</mediaobject>
      </screenshot>
      <para>
        The previous example was a simple one, and limited to just
	text.  However, there is also support for showing variable
        information about objects in a label  (e.g. you can construct
        a label showing the text "This segment is %1 units long.." 
        where "%1" would be replaced with the length of a specific
        segment).
      </para>
      <para>
        To do this, enter text with a number of placeholders ( "%1",
        "%2", "%3" etc. ) in it.  When you are
        finished, press the <guibutton>Next</guibutton> button to
        continue. If you want to change the text or variables later, you can go back using the
        <guibutton>Back</guibutton> button.
      </para>
      <para>
        The wizard now shows the text you entered with all
        placeholders replaced by something like "argument 1".
        Selecting what to show as a certain argument is done by first
        clicking the argument in question.  Then click on the object
        about which you want to show information, and then select an
        interesting piece of information in the popup menu that
        appears.  E.g. in the example above, you would click "argument
        1", click on the correct segment in the main &kig; window, and
        select the property "Length".  Afterwards, you can fill in the
        rest of the variable parts, or select another property for
        one of the variable parts if you wish to change it.  When
        you are ready, click the <guibutton>Finish</guibutton> button
        to complete the construction of the text label.
      </para>
      <screenshot>
	<screeninfo>Selecting a property for a variable
	part</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata
	    fileref="text_label_wizard__select_property.png"
	    format="PNG"/>
	  </imageobject>
	  <textobject>
	    <phrase>Selecting a property for a variable part</phrase>
	  </textobject>
	</mediaobject>
      </screenshot>
    </section>
  </chapter>

  <chapter id="kig-object-types">
    <title>&kig; Object Types</title>
    <para>
      &kig; supports a rather large number of object types.  You are
      encouraged to try out the various objects, as I think this is a
      better way to find out about them than reading about them in
      some boring manual ;).  Please note that not all of the available
      object types are shown in the toolbars, but that there are also
      some objects that you can only construct via the
      <guimenu>Objects</guimenu> menu in the menu bar.  Of course, as
      with all &kde; applications, what appears in the toolbars is
      configurable.  Try out the
      <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure
      Toolbars...</guimenuitem></menuchoice> option if you want to do
      this.
    </para>
  </chapter>

  <chapter id="kig-features">
    <title>&kig; Features</title>
    <para>
      <itemizedlist>
	<listitem>
	  <para>
	    &kig; is an open source application.  This means that you
	    are free to use and modify it any way you like it.
	    Distributing &kig; is subject to some restrictions,
	    basically that everyone should have the same rights to use
	    &kig;, including your modifications, as you and me.
	  </para>
	  <para>
	    Free software programs are developed in a very open
	    spirit, and its developers are usually very responsive to
	    user feedback.  Therefore, if you have any questions,
	    complaints, or whatever about kig, please let me know at <email>devriese@kde.org</email>.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    &kig; is a KPart application, which means that you can
	    embed it in other &kde; software.  If you open a <literal
	    role="extension">.kig</literal> file in &konqueror;, it
	    can be opened directly in the &konqueror; screen without
	    the need to start an external application.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Working with &kig; should be very straightforward.
    Constructing objects is easy and interactive, with preliminary
	    results being shown, etc.  Moving, selecting and building all
	    work as one would expect them to.  Undo support should
	    also be very intuitive.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    &kig; supports macros to be defined in a straightforward
	    manner.  These objects are presented to the user like
	    normal objects.  They are saved on exit and loaded on
	    startup, so that they aren't lost on exit.  In the <link
	    linkend="working-with-types">Types Manager</link> you can
	    manage these objects.  You can export them to files, import
	    them from files, and delete them.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    &kig; saves its data in a clear &XML; format.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    &kig; supports the construction of locuses..
	  </para>
	</listitem>
	<listitem>
	  <para>
	    &kig; has an option "Export to image"..  This is rather
	    useful, since not all programs support the &kig; file
	    format yet ;).
	  </para>
	</listitem>
	<listitem>
	  <para>
	    &kig; has a very flexible transformation system.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    &kig; allows you to export a kig file to some interesting
	    formats, like images, and XFig files, which are useful for
	    inclusion in LaTeX and other documents.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    &kig; aims to be compatible with its competitors.. This is
	    why it supports the &kgeo; file format, the &kseg; file
	    format, and I'm working on other formats as well.
	  </para>
	</listitem>
      </itemizedlist>
    </para>
  </chapter>

  <chapter id="contributing">
    <title>Contribute</title>
    <section id="kig-is-free">
      <title>Free Software</title>
      <para>
	&kig; is <ulink
	url="http://www.gnu.org/philosophy/philosophy.html#AboutFreeSoftware">
	Free Software</ulink>.  This means that its source code is
	freely available on the internet, and everyone can use it,
	read it, modify it, and distribute it.  I work on it as a
	hobby project, and I have already learned a lot about programming,
	C++, KDE/Qt, math, software colaboration and open source
	projects in the process.
      </para>
    </section>
    <section id="contribute-to-kig">
      <title>Contribute</title>
      <para>
	The point of this chapter is to point you ( the user ) to the
	rights that &kig;'s license gives you.  As with all free
	software, you are allowed ( and encouraged :) to fix problems
	you encounter while using it, to add features you miss, to
	distribute your modified program, and to send these
	modifications to me at 
<email>devriese@kde.org</email>, so that I can include them
	in the next version for others to enjoy.  I personally have no
	financial interest in this project whatsoever, so this isn't
	just marketing-speak here ;).
      </para>
      <para>
	If you are uncertain of your rights to use this software, or
	other peoples right to use any modifications you make to this
	program etc., please read the license.  You can find it in the
	COPYING file in the &kig; source tree or the license tab in
	the About Kig dialog.
      </para>
    </section>
    <section id="howto-contribute">
      <title>How to contribute ?</title>
      <para>
	Any contributions are welcome.  If you think the icons suck,
	or that the manual needs updating, or you have this really
	cool macro that you want to share with the world, do not
	hesitate to send it to me.  Please note that your
	contributions will be distributed under the terms of the GNU
	GPL; you can find the terms of this license in the COPYING
	file in the &kig; source tree, and further along in this
	manual...
      </para>
    </section>
  </chapter>

  <chapter id="faq">
    <title>Questions and Answers</title>

    &reporting.bugs; &updating.documentation; <para></para>
  </chapter>

  <chapter id="credits">
    <title>Credits and License</title>

    <para>
      &kig;
    </para>
    <para>
      &kig; copyright 2002 Dominique Devriese
      <email>devriese@kde.org</email>
    </para>

    <para>
      Documentation copyright 2002 Dominique
      Devriese. <email>devriese@kde.org</email>
    </para>
    <!-- TRANS:CREDIT_FOR_TRANSLATORS --> &underFDL; &underGPL;
  </chapter>

  <appendix id="installation">
    <title>Installation</title>

    <sect1 id="getting-kig">
      <title>How to obtain &kig;</title>

      &install.intro.documentation;

    </sect1>

    <sect1 id="compilation">
      <title>Compilation and Installation</title>
      &install.compile.documentation;
    </sect1>

  </appendix>

  &documentation.index;
</book>
<!-- 
Local Variables:
mode: xml
End:
-->

