# &koffice;

## Still to be done in this manual

This is a list of things which still need work in this manual:

- Write this list.

- Just about everything else.

If anyone wants to help, let me know at the email address below. Thanks.

Jost jost@schenck.de

## Introduction

&koffice; is an integrated office suite for the K Desktop Environment (&kde;). &koffice; currently consists of the following programs:

- &kword; (a frames-based wordprocessor)
- &kspread; (a spreadsheet application)
- &kpresenter; (screen and slide presentations)
- &kontour; (a vector drawing application)
- &kformula; (an editor for mathematical formulae)
- &kchart; (a charts/graphs drawing application)
- &kivio;
- &kugar;

Because they are based on the KParts component model, &koffice; programs are designed to work very well with each other. Any &koffice; component can be embedded in another &koffice; document. For instance, you can insert a table which you created in &kspread; directly into a &kword; document. In this way, complex, compound documents can be created using &koffice; programs.

A plug-in mechanism makes it easy to extend the functionality of &koffice;. Already, there are two applications, a macro recorder and a calculator, which show how this can be done.

This manual only covers the general features of &koffice;, those that are common to most or all programs in the suite. For detailed information about the different programs, have a look at the other manuals.

## First steps in &koffice;

## KParts - the building blocks of &koffice;

Each &koffice; application is designed to fulfill very specific needs. For example, &kspread; is a program for manipulating spreadsheets, while &kword; is a program for word processing. By focusing on a specific area, each program aims for perfection in exactly this area. However, depending on what you do with &koffice;, you'll often want to take advantage of functionality provided by different applications, but in the same document.

Suppose that you are preparing a document in &kword; and want to illustrate some point using a table. While &kword; provides its own functionality for the insertion of tables, this may not be enough for your needs. For example, you may want to use certain currency data formats or to do calculations using spreadsheet formulae. Now, some &kword; programmer certainly could try to implement this functionality. However, &kword; would never be as good as &kspread; in this field; and if it tried to implement all the functionality you might possibly need, it would end up becoming unreasonably complex and the source code would become impossible to maintain.

The alternative to this is KParts. Its philosophy is simple: let every application do what it does best.

### Compound documents with KParts

With KParts, your documents can use all functionality offered by all &koffice; applications. You can take advantage of this by inserting so-called parts into your document. Every one of those parts is essentially another document, that is, a document within a document.

In the example mentioned above, you would simply insert a &kspread; part into your &kword; document. Then, whenever you edit your table, &kspread; would take control in the background. Control would return to &kword; when you stop working on the table and start working on text again. The only change you would notice is that the toolbars and menus, while editing the table, reflect the functionality of &kspread; instead of that of &kword;. This ability to include the functionality of one application in another is called embedding.

### Using KParts in your document

If you have never worked with compound documents, you may find them confusing at first. The following step-by-step instructions show you that using KParts is just as easy as working with a single application.

### Inserting a &kspread; part into a &kword; application

1. Start &kword;. You can do that either from the panel or by typing ``kword`` at the command line.

2. Start a new, blank document. You may want to type some sample text.

3. Chose Create KSpread table frame from the Tools menu. You'll notice that the mouse cursor has changed to a cross. This form of the cursor indicates that you are supposed to select an area.

4. Press the &LMB; mouse button where you want the upper left corner of your table to be, hold it and drag it to the lower right corner. Release the button. That's it--you're done.

Easy, isn't it? You should now see a table frame in your &kword; document. Now, click inside the table to see what happens. You'll notice that:

- Your menu bar and tool bars have changed. They now reflect those of &kspread;.

- Your table frame now contains the elements of a &kspread; view, with scroll bars, a tab bar for the selection of tables, &etc;

Try editing the table. You'll see that it's not different from using &kspread;. In fact you are using &kspread;.

Now click somewhere into your &kword; document, outside of the table area. The menu bar and tool bars should change back to those of &kword;, the elements of the &kspread; view should disappear. Your table stays and still reflects all of the changes you've applied to it.

KParts are easy to use. Try inserting other parts or even parts in parts.

## Optimizing &koffice; and Your System

While &koffice; should work quite nice out of the box, there may well be some things to optimize to get the best out of &koffice;. This chapter shows you what you might want to do to achieve the best results with your new office suite.

### Optimizing Font Output

Fonts are a difficult topic on X Windows. In this section we'll cover some problems that are frequently reported by people using &koffice;. Some problems are not just &koffice;s fault, but depend on your system configuration, which is why you may need to modify system configuration files in order to solve them. If you don't have access to the root account on your system, please ask your system operator about this and point him or her to this manual. As the topic of fonts is too complex to cover all of it here, you may want to consult the Font HOWTO from which I've taken the following information. You will find more details there.

#### How to Get Nicely Scaled Fonts on Screen

STUFF

#### How to Get Correct Printout

While &koffice; automatically can handle all X11 fonts on screen, printout can pose a problem: on most systems, printing is done via ghostscript. Now, while &koffice; knows the font names used by X Windows, it does normally not know the font names used by ghostscript. &koffice; tries to guess these names, which unfortunately doesn't work all of the time.

This problem can be solved, although this is not that easy. Actually, maybe you are using a distribution which has done most work for you already (so if you have no reason to complain about printout you can skip this section). What you have to do is to tell ghostscript how to translate the (guessed) font names &koffice; uses to its own font names. This can be done by adding lines to a file called `Fontmap`. An alias line in `Fontmap` looks like the following example:

##### An alias in the ghostscript Fontmap

    /Algerian-Roman /Algerian       ;

Please note that a space before the ';' is mandatory. In this example, Algerian-Roman is the name &koffice; uses for Algerian. You'll have to add such lines for the fonts &koffice; doesn't display correctly. To make this task easier, Donovan Rebbechi has written a perl script you can find at http://pegasus.rutgers.edu/~elflord/font_howto/kwdfont. Assuming that you have a fontfile `/usr/share/ghostscript/fonts/fontfile.ttf` you'll enter ``kwdfont` `/usr/share/ghostscript/fonts/fontfile.ttf`` to get the appropriate aliases. The script should mork in most cases. As mentioned, you should have a look at the Font HOWTO for more accurate and in-depth information.

### Customizing the &koffice; &GUI;

While &koffice; comes out of the box with a &GUI; (graphical user interface) that should suit most people's needs, there are good reasons why you may want to change the way the programs look.

My mother, for example, is a bit afraid of buttons and menu entries she doesn't understand. To tailor &koffice; to her needs, I reduced the &GUI; to a bare minimum of functionality. As she only needs to write letters and use certain templates, there is no need for much more functionality than saving, loading, printing, &etc;

Thanks to the action concept of &Qt; and &kde;, you can freely customize &koffice; menu bars and tool bars. Unfortunately, at the moment, there are no easy-to-use dialogs to do this. &koffice; stores its &GUI; configuration in &XML; files and you'll have to edit those. Hopefully, this situation will change in the future; for now, you'll need some basic knowledge of how an &XML; document works (or HTML, which is a subset of &XML;). [The action concept needs to be discussed in more detail -- kt.]

Normally, each &koffice; application has at least two of those &XML; files: one describing the &GUI; of the shell (basically, that's what you see if there is no document open) and one describing the &GUI; of the respective part (that's what you see normally). For example, for &kword;, these two &XML; files are named `kword_shell.rc` and `kword.rc`.

Here's a simple example of such an rc-file.

#### An example of a simple rc-file

    <!DOCTYPE QConfig ><qconfig>
    <menubar>
    <menu name="Edit"><text>Edit</text>
    <action name="edit_cut"/>
    <action name="edit_copy"/>
    <action name="edit_paste"/>
    <separator/>
    <action name="edit_find"/>
    </menu>
    <menu name="Insert"><text>Insert</text>
    <action name="insert_picture"/>
    <action name="insert_clipart"/>
    <menu name="Variable"><text>Variable</text>
    <action name="insert_var_datefix"/>
    <action name="insert_var_datevar"/>
    </menu>
    </menu>
    </menubar>
    <toolbars>
    <toolbar name="edit_toolbar" position="right">
    <action name="edit_cut"/>
    <action name="edit_copy"/>
    <action name="edit_paste"/>
    </toolbar>
    </toolbars>
    </qconfig>

## How to get more information

### Other &koffice; manuals

For detailed information on the different &koffice; applications, please consult their respective manuals.

### Links

The following links should be useful if you're looking for more information about &kde; or &koffice;.

- The &koffice; homepage. Here you can find information on how to get and install &koffice;, news about &koffice; development, screenshots &etc;

- &kde-http;. The most advanced and absolutely free desktop environment for unix-like operating systems. &koffice; makes use of the &kde; libraries.

- Troll Tech. The creators of the C++-toolkit &Qt;. &kde; and &koffice; make use of &Qt;.

## Programming &koffice;

If you want to do &koffice; development, the following resources might be of interest:

- At http://developer.kde.org you'll find many documents about programming with &Qt; and &kde;. Here you can find the online version of the complete &kde; library documentation.

- Use kdoc (in the `kdoc` CVS module) to generate your own &kde; library documentation.

- In the &koffice; sources you'll find an example application in the `example` directory.

## Copyright and Licensing

&koffice; is copyrighted by the &koffice; team.

This manual is copyright by Jost Schenck. It can be distributed freely, as long as this copyright notice is included. You may change it as long as you send me the changes or commit them to &kde; CVS. I'll not be liable for anything resulting from the use of this manual.

The other &koffice; manuals are copyrighted by their respective authors.

&underFDL; &underGPL;

## Installation

### System Requirements

In order to install and use &koffice; you must have:

- A functioning &UNIX; system (for example, &Linux; or BSD) with a configured &X-Window; (for example, XFree86).

- The &Qt; 2.1 libraries from Troll Tech. See ftp://ftp.troll.no/ for more information.

- The K Desktop Environment 2.0 (&kde; 2.0). &koffice; cannot be compiled with earlier versions of &kde;. Information on obtaining and installing &kde; 2.0 can be found at: &kde-http;

- Permission to install software on your computer. If you are on a stand-alone system, this should not be a problem. However, if you are using a networked computer, check with your administrator first.

Please note that, while you need the &kde; 2.0 libraries on your system, you can still use &koffice; in a different desktop environment (for example, &kde; 1.1, UDE or GNOME).

If you plan on compiling &koffice; from source code you will also need:

- `automake` 1.4 or newer. This can be downloaded from: ftp://ftp.gnu.org/pub/gnu/automake/

- `autoconf` 2.13 or later. This can be downloaded from: ftp://ftp.gnu.org/pub/gnu/autoconf/

- A C++ compiler which supports exceptions (preferably egcs 1.1.x). This can be downloaded from http://egcs.cygnus.com/

- Troll Tech's &Qt; 2.1 development packages. These can be downloaded from ftp://ftp.troll.no/

Once you have determined that your system meets these requirements, you should decide whether you want to compile the source code or install from pre-compiled binary packages.

If you want to obtain the most current binary version of KOffice, you can find more information by following this link: Getting Binary Packages.

If pre-compiled binaries are not available for your system, you can download the source code and compile it yourself. Instructions on where to obtain the current source code (and what to do with the source code once you have it) can be found by following this link: Getting the source code.

Please see the &koffice; homepage for further details. That is where you can always find the most up-to-date information on both source and binary distributions!

### Getting Binary Packages

You can download the most current binaries from:

http://koffice.kde.org/

or from one of many mirror sites. The current list of mirror sites can be found at:

http://www.kde.org/mirrors.html

It is important that you use a binary package which is compatible with your system. If you use the &Linux; operating system and are unable to find a binary package at the &koffice; web site or one of its mirrors, you may be able to obtain one from the website of your distribution.

### From Binary Packages

To install &koffice; from precompiled binaries, you should:

1. Ensure your computer has all of the required software installed and in working condition (excluding &koffice; of course). You can find the system requirements by following this link: System Requirements.

2. Download the &koffice; binary into a temporary directory.

3. If the filename ends in `.rpm` (&RedHat; Package Management file), &koffice; can be installed with the following command:

       $
       rpm-Ufilename

   .

   If thefilename ends in `.deb` (Debian Package file), &koffice; can be installed with the following command:

       $ dpkg-i
       filename

   If the filename ends in `.tar.gz` or `.tgz` (a tarball file), &koffice; can be installed with the following commands:

       $ cd /
       $ tar -xzvf filename

4. That's all. &koffice; should now be installed on your system.

If you have a graphical front-end for package management, such as &kpackage; or GnoRPM, installed on your system, you may find that more convenient to use than a command line. Consult the program's documentation to find out how to install with it.

### Getting Source Code

You can download the current source code from: http://koffice.kde.org/ or from one of many mirror sites. The current list of mirror sites can be found at:

http://www.kde.org/mirrors.html

### From Source Code

If you want to build &kword; from source code, you should:

1. Ensure your computer has all the required software installed and in working condition (excluding &koffice; of course). You can find the system requirements by following this link: System Requirements.

2. Download the &koffice; source file into a temporary directory.

3. If the filename ends in `.src.rpm` (&RedHat; Package Management file), the source code for &koffice; can be installed with:

       $ rpm-Ufilename

   If the filename ends in `.src.tar.gz` or `.src.tgz` (a tarball file), the source code for &koffice; can be installed with:

       $ tar -xzvf filename

4. The source code for &koffice; should now be installed on your system.

### Problems with Compilation

To be written

&documentation.index;