katapult/doc/en/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!-- Define an entity for your application if it is not part of KDE
       CVS -->
  <!ENTITY katapult "<application>Katapult</application>">
  <!ENTITY kappname "&katapult;">
  <!ENTITY package "extragear">
  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>

<book lang="&language;">
  <bookinfo>
    <title>The &katapult; Handbook</title>
    
<authorgroup>
  <author>
    <firstname>Richard</firstname>
    <othername>A.</othername>
    <surname>Johnson</surname>
    <affiliation><address><email>nixternal@ubuntu.com</email></address></affiliation>
  </author>
</authorgroup>

<!-- TRANS:ROLES_OF_TRANSLATORS -->

<copyright>
  <year>2005</year>
  <holder>Martin Meredith</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2006-11-17</date>
<releaseinfo>1.00.00</releaseinfo>

<abstract>
  <para>
    &katapult; is an application specially designed to provide quick and easy access to applications, bookmarks, music and more.
  </para>
</abstract>

<!-- This is a set of Keywords for indexing by search engines.
Please at least include KDE, the KDE package it is in, the name
 of your application, and a few relevant keywords. -->

<keywordset>
  <keyword>KDE</keyword>
  <keyword>extragear</keyword>
  <keyword>Katapult</keyword>
  <keyword>application launcher</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
  <title>Introduction</title>
  <para>
    &katapult; is a &kde; application that provides you with faster and easier access to your applications, bookmarks, and more. It is plugin-based and can launch anything it has a plugin for. Its plugin-driven appearance is completely customizable. &katapult; was inspired by <application>Quicksilver</application> for OS X, and it is written in C++.
  </para>
</chapter>

<chapter id="using-kapp">
  <title>Using &katapult;</title>
  <sect1 id="starting">
    <title>Starting &katapult;</title>
    <para>
      &katapult;, if not started automatically upon booting into &kde;, can simply be started by 
      <keycombo>
        <keycap>Alt</keycap>
        <keycap>F2</keycap>
      </keycombo>
      . When the run dialog box opens, type <command>katapult</command> and press <keycap>Enter</keycap>. If &katapult; started successfully, you will receive a pop-up message with instructions on how to use the launcher.
      <screenshot>
        <screeninfo>Here's a screenshot of the &katapult; start-up message</screeninfo>
        <mediaobject>
          <imageobject>
            <imagedata fileref="katapult0.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Screenshot</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </para>
  </sect1>
  
  <sect1 id="launching">
    <title>Launching &katapult;</title>
    <para>
      To launch &katapult;, simply press 
      <keycombo>
        <keycap>Alt</keycap>
        <keycap>Space</keycap>
      </keycombo>
      . This will pop up the &katapult; launcher, allowing you to type in the name of the application you wish to launch.
      <screenshot>
        <screeninfo>Here's a screenshot of the &katapult; launcher</screeninfo>
        <mediaobject>
          <imageobject>
            <imagedata fileref="katapult1.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Screenshot</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </para>
  </sect1>
  
  <sect1 id="katapult-features">
    <title>More &katapult; features</title>
    <para>
      &katapult; allows access to the following:
      <itemizedlist>
        <listitem>
          <para>
            All applications listed in <guimenu>KMenu</guimenu>
          </para>
        </listitem>
        <listitem>
          <para>
            Entire <application>Amarok</application> playlist
          </para>
        </listitem>
        <listitem>
          <para>
            All of you bookmarks (Automatic Mozilla import, or manual import of file)
          </para>
        </listitem>
        <listitem>
          <para>
            Use &katapult; as a calculator
          </para>
        </listitem>
        <listitem>
          <para>
            Use &katapult; to see if you are spelling a word correctly
          </para>
        </listitem>
        <listitem>
          <para>
            Easy access to all of your documents in the home directory
          </para>
        </listitem>
      </itemizedlist>
    </para>
  </sect1>
</chapter>

<chapter id="commands">
  <title>Command Reference</title>
  <sect1 id="katapult-mainwindow">
    <title>The main &katapult; window</title>
    <para>
      When the main &katapult; window opens, simply start typing the application you want to start, and then press <keycap>Enter</keycap> to launch that application. Example, to start &konqueror;, you would do:
        <keycombo>
          <keycap>Alt</keycap>
          <keycap>Space</keycap>
        </keycombo>
      Then start typing &konqueror; Once you have typed in at least <command>konq</command>, you will notice the Konqueror title and icon appear in the main window. Once you see this, simply press <keycap>Enter</keycap>, and &konqueror; will now open.
      <screenshot>
        <screeninfo>Here's a screenshot of &katapult; starting &konqueror;</screeninfo>
        <mediaobject>
          <imageobject>
            <imagedata fileref="katapult2.png" format="PNG"/>
          </imageobject>
          <textobject>
            <phrase>Screenshot</phrase>
          </textobject>
        </mediaobject>
      </screenshot>
    </para>
        
    <sect2>
      <title>Configuration Dialog</title>
      <para>
        In normal cases &katapult; shows up in the system tray. Simply <mousebutton>right</mousebutton> click and choose <guimenuitem>Configure</guimenuitem>. This will allow you to change &katapult;'s default behavior and appearance.
      </para>
      <para>
        If &katapult; does not show up in the system tray, simply press 
        <keycombo>
          <keycap>Alt</keycap>
          <keycap>Space</keycap>
        </keycombo>
        . Once &katapult; launches, then press 
        <keycombo>
          <keycap>Ctrl</keycap>
          <keycap>C</keycap>
        </keycombo>
        . From here you have the options to:
        <itemizedlist>
          <listitem>
            <para>
              <guimenuitem>Configure Global Shortcuts...</guimenuitem> - This will allow you to change the 
              <keycombo>
                <keycap>Alt</keycap>
                <keycap>Space</keycap>
              </keycombo>
               shortcut to one you decide to use.
             </para>
           </listitem>
           <listitem>
             <para>
               <guimenuitem>Configure Shortcuts...</guimenuitem> - This will allow you to change all shortcuts involved with the &katapult; launcher
             </para>
           </listitem>
           <listitem>
             <para>
               <guimenuitem>Configure Katapult...</guimenuitem> - This will allow you to to change each individual catalog as well as &katapult; itself to suit your needs.
             </para>
           </listitem>
           <listitem>
             <para>
               <guimenuitem>About Katapult</guimenuitem> - This will open the about dialog displaying information about &katapult;, the &katapult; authors, and the &katapult; license agreement.
             </para>
           </listitem>
           <listitem>
             <para>
               <guimenuitem>Quit</guimenuitem> - This will shut down &katapult;.
             </para>
           </listitem>
         </itemizedlist>
       </para>
     </sect2>
   </sect1>
</chapter>

<chapter id="catalog-creation">
  <title>Creating a Catalog (Plugin)</title>
  <sect1 id="plugin-intro">
    <title>Introduction</title>
    <sect2 id="plugin-intro-purpose">
      <title>Purpose</title>
      <para>
        This section of the documentation is intended for those people looking to develop catalogs (plugins) for &katapult;. It will approach this as a walk-through for creating a text display catalog.
      </para>
    </sect2>
    <sect2 id="plugin-intro-assumptions">
      <title>Assumptions</title>
      <para>
        It is assumed that you are running &kde; 3.5 or greater. Additionally, <application>KDevelop</application> will be the primary coding environment.
      </para>
    </sect2>
    <sect2 id="plugin-intro-overview">
      <title>Overview</title>
      <para>
        What you will be doing is actually something simple: you are making a library for KDE. This library defines a &quot;Service&quot; that is provided for &katapult; and can therefor be used and called by &katapult;. All of your code will be compiled and then combined into a library (.lo, .so) by <application>KDevelop</application>. It will be added into the $KDE_LIBS/trinity/ directory, and a .desktop &quot;service definition&quot; file will be placed in $KDE/share/services/ so that &katapult; can load your plugin.
      </para>
    </sect2>
  </sect1>
<!-- 
  <sect1 id="understanding-source">
    <title>Understanding the source</title>
    <para>
      Enter information here
    </para>
  </sect1>
-->
  <sect1 id="plugin-structure">
    <title>Catalog Structure</title>
    <sect2 id="plugin-structure-common">
      <title>Common Directory</title>
      <sect3>
        <title>libkatapult.la</title>
        <itemizedlist>
          <listitem>
            <para>
              ActionRegistry
            </para>
          </listitem>
          <listitem>
            <para>
              KatapultAction - events
            </para>
          </listitem>
          <listitem>
            <para>
              KatapultItem - the text that is entered
            </para>
          </listitem>
        </itemizedlist>
      </sect3>
      <sect3>
        <title>libkatapultcatalog.la</title>
        <itemizedlist>
          <listitem>
            <para>
              CachedCatalog
            </para>
          </listitem>
          <listitem>
            <para>
              KatapultCatalog
            </para>
          </listitem>
          <listitem>
            <para>
              Match
            </para>
          </listitem>
        </itemizedlist>
      </sect3>
      <sect3>
        <title>libkatapultdisplay.la</title>
        <itemizedlist>
          <listitem>
            <para>
              ImageDisplay
            </para>
          </listitem>
          <listitem>
            <para>
              ImageDisplaySettings
            </para>
          </listitem>
          <listitem>
            <para>
              KatapultDisplay
            </para>
          </listitem>
        </itemizedlist>
      </sect3>
    </sect2>
    <sect2 id="plugin-structure-catalogs">
      <title>Plugin Catalog Structure</title>
      <para>
        This is where your catalog's directory will go. The format is &lt;name&gt;catalog, where &lt;name&gt; is replaced by your catalog's name. You may want to copy over some of the files from one of the standard catalogs into your new directory so that you have a starting point or something to play with.
      </para>
    </sect2>
  </sect1>
<!--
  <sect1 id="starting-to-code">
    <title>Starting to code</title>
    <para>
      Enter information here
    </para>
    <sect2 id="starting-to-code-kdevsetup">
      <title>Setting up &tdevelop;</title>
      <para>
        Enter information here
      </para>
    </sect2>
  </sect1>
-->
</chapter>

<chapter id="credits">
  <title>Credits and License</title>
  <para>
    &katapult;
  </para>
  <para>
    Program copyright 2005, the Katapult Development Team <email>dev@thekatapult.org.uk</email>
  </para>
  <para>
    Developers:
    <itemizedlist>
      <listitem>
        <para>
          Martin Meredith <email>mez@thekatapult.org.uk</email>
        </para>
      </listitem>
      <listitem>
        <para>
          Bastian Holst <email>oculus@thekatapult.org.uk</email>
        </para>
      </listitem>
      <listitem>
        <para>
          Tobi Vollegregt <email>tobi@thekatapult.org.uk</email>
        </para>
      </listitem>
    </itemizedlist>
  </para>
  <para>
    Contributors:
    <itemizedlist>
      <listitem>
        <para>
          Richard Johnson <email>nixternal@ubuntu.com</email>
        </para>
      </listitem>
      <listitem>
        <para>
          Jean-Remy Falleri <email>jr.falleri@gmail.com</email>
        </para>
      </listitem>
      <listitem>
        <para>
          Lee Olson <email>clearbeast@gmail.com</email>
        </para>
      </listitem>
      <listitem>
        <para>
          Jonathan Riddell <email>jr@jriddell.org</email>
        </para>
      </listitem>
    </itemizedlist>
  </para>
  <para>
    Original Author:
    <itemizedlist>
      <listitem>
        <para>
          Joe Ferris <email>jferris@optimistictech.com</email>
        </para>
      </listitem>
    </itemizedlist>
  </para>
  <para>
    Documentation Copyright &copy; 2006, Richard Johnson <email>nixternal@ubuntu.com</email>
  </para>
    
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;               <!-- FDL: do not remove -->
&underGPL;

</chapter>

<appendix id="installation">
  <title>Installation</title>
  <sect1 id="getting-kapp">
    <title>How to obtain &katapult;</title>
    <sect2>
      <title>KDE Subversion</title>
      &install.intro.documentation;
    </sect2>
    <sect2>
      <title>Distribution &amp; Source Packages</title>
      <para>
        Available distribution packages and source packages can be obtained through <ulink url="http://wiki.thekatapult.org.uk/Download">http://wiki.thekatapult.org.uk/Download</ulink>.
      </para>
    </sect2>
  </sect1>
  <sect1 id="requirements">
    <title>Requirements</title>
    <itemizedlist>
      <listitem>
        <para>
          &kde; 3.4.x and above
        </para>
      </listitem>
      <listitem>
        <para>
          gcc 3.3 or higher
        </para>
      </listitem>
    </itemizedlist>
  </sect1>
  <sect1 id="compilation">
    <title>Compilation and Installation</title>
    <note>
      <title>Source Package Instructions Only</title>
      <para>
        Note the following instructions are for the source package only. If you are installing a distribution package, please follow the instructions for that distribution.
      </para>
    </note>
    <sect2>
      <title>Extracting the source</title>
      <para>
        Open a terminal (&konsole;), and navigate to the directory in which you saved the source. Once there, type <command>tar -zxf katapult_&lt;version&gt;.orig.tar.gz</command>, and then press <keycap>Enter</keycap>.
      </para>
    </sect2>
    <sect2>
      <title>Compiling</title>
      <para>
        At the command prompt, in the terminal (&konsole;), type <command>./configure</command> and then press <keycap>Enter</keycap>. When that finishes, at the command prompt, type <command>make</command> and press <keycap>Enter</keycap>.
      </para>
    </sect2>
    <sect2>
      <title>Installing</title>
      <para>
        At the command prompt, in the terminal (&konsole;), type <command>sudo make install</command> and press <keycap>Enter</keycap>. If you are asked for a password, enter you username's password and press <keycap>Enter</keycap>.
      </para>
    </sect2>
  </sect1>
</appendix>

&documentation.index;
</book>