]>

# KOffice

A General Introduction
Jost
Schenck
KDE
KOffice
21/03/2000
0.1.1
0.1.1
21/03/2000
KT
Proof-read version of 0.1.0. Also, some minor changes (couldn't stop myself :)
0.1.0
27/01/2000
JS
First made available to the CVS

&KOffice; is an integrated office suite for the K Desktop Environment (KDE).

## 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

### 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)
- KIllustrator (a vector drawing application)
- KImageShop (a bitmap image editor)
- Katabase (a database application)
- KFormula (an editor for mathematical formulae)
- KChart (a charts/graphs drawing application)
- KImage (an image viewer)

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. FIXME LINK!

### What parts of this guide should I read?

This section is not yet written.

## 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 System (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: http://www.kde.org.

- 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 -U filename

   If the filename 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 command:

       $ 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 (***insert filenames (srpm and tar) here***) 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 -U filename

   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.

STUFF

### Problems with Compilation

Problems STUFF

## 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. [I think this para needs more elaboration -- kt.]

### 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. (FIXME: I think this menu structure was supposed to be changed). 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 left 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

     Edit

     Insert

      Variable

    ]]>

## How to get more information

### Other &KOffice; manuals

For detailed information on the different &KOffice; applications, please consult their respective manuals. [FIXME: how do I provide links to them? Do we need set-tag?]

### 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.

- The K Desktop Environment (KDE). 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.

## Frequently Asked Questions

## Copyright and Licensing

KOffice is copyrighted by the KOffice team. KOffice is licensed mainly under the terms of the GNU GPL.

Some programs are licensed under the terms of the Artistic License. FIXME: put artistic-license.html in common!

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.

## Glossary

### ?

### A

### B

### C

### D

### E

### F

### G

### H

### I

### J

### K

KDE

  The K Desktop Environment (KDE) is a completely free desktop environment for unix-like operating systems. &KOffice; uses the KDE-2.0 libraries. See http://www.kde.org for details.

KParts

  KParts is a technology that allows the embedding of components ("parts") in an application. This way, you can create compound documents in &KOffice;, e.g. a &KWord; document containing a &KSpread; table.

### L

### M

### N

### O

### P

Part

  A part is an application which can be embedded into other KParts applications.

### Q

Qt

  Qt is the underlying toolkit that was used for KDE and &KOffice;. See http://www.troll.no for details.

### R

### S

### T

### U

### V

### W

### X

### Y

### Z