# The &kformula; Users Manual

Jonathan
Drews

    j.e.drews@att.net

Ulrich
Küttler
Developer
&FDLNotice;
2002-02-19
0.00.02

&kformula; is used to layout formulas.

KDE
KOffice
kformula
formula

## Introduction

&kformula; is used to write formulas. It doesn't evaluate anything. All it does is print them.

&kformula; was designed for your editing pleasure. It makes it delightful to enter Greek letters, fractions and all the stuff that makes a formula look like a formula.

But most of the time you won't want to use &kformula; itself. Instead you might choose to use it from within &kword; or any other &koffice; application. That is &kformula; is not a useful application on its own but an extension to all the other &koffice; applications you've fallen in love with.

Where ever &kformula; gets embedded, it will behave the same.

## Basics

A new (empty) &kformula; document looks like a small blue square. This square stands for the central idea of &kformula;. It represents an empty list. The idea of &kformula; is to have different elements arranged in lists. An element in this respect might be a single char or a root symbol or something like that. The lists are put together so that they form a formula. That is there are lists for indexes, lower and upper bounds and so on. And of course there is the main list, which we've already seen.

Writing a formula means to fill the empty list with letters, figures and mathematical symbols. That is straightforward: use your keyboard. As soon as you type something the empty symbol will vanish and you will see whatever you have inserted instead. New characters are always put at the current cursor position.

There is a toolbar called Add that allows you to create more complex elements. There are indices, fractions, roots and matrices to name a few. All these elements consist of at least one list, you can move the cursor into and insert new items.

## Using &kformula;

Below is a typical formula entry in &kformula;. To enter the partial derivatives and Greek letters click on the symbol combo box, on the right, and select the appropriate symbol. The symbol combo box, in the figure below, has the word Cap on it. Click on the return key symbol to the right of it, to enter a symbol.

Screenshot of &kformula;
Screenshot of &kformula;

The Greens formula above can be printed to a &PostScript; file. To do that choose File Print and configure print as shown below:

Here's a screenshot of Greens Formula in &kformula;
Here's a screenshot of Greens Formula in &kformula;

Here is what the the resulting &PostScript; file should look like:

Here is the &PostScript; output from &kformula;

See the Mathematical Fonts section for font installation details. You must install the bakoma or esstix fonts to get these results

### More &kformula; features

More on formulas

To enter matrices, click on the [ ] and then click on the matrix symbol . You can move from matrix element to matrix element using the arrow keys Right arrow, Up arrow, Down arrow and Left arrow. An example matrix is shown below.

Here is the resulting matrix;

## Command Reference

### The main &kformula; window

#### The File Menu

&Ctrl;N File New

  Creates a new &kformula; document

&Ctrl;O File Open

  Opens a previously saved document

File Open Recent

  displays a selection of recently saved documents you can open

&Ctrl;S File Save

  Saves the document

File Save As

  Saves the document with a name you provide

&Ctrl;P File Print

  Prints the document

File Print Preview...

  Shows how the printed document will appear

File Document Information...

  Provides a dialog box where you can enter your name, email address and a short description about the document

File Send File...

  Invokes Kmail so you can email the file. Note: You still have to attach the file to the email

&Ctrl;W File Close

  Closes the current document

&Ctrl;Q File Quit

  Quits &kformula;

#### The Edit Menu

&Ctrl;Z Edit Undo

  Undoes an action. You can revert to the state that existed before your last change

&Ctrl; &Shift; Z Edit Redo

  Undoes an undo. Reverse the action of Undo. This will restore the change you originally made

&Ctrl;X Edit Cut

  Cuts a highlighted piece of text from the &kformula; screen.

&Ctrl;C Edit Cut

  Copies a highlighted piece of text from the &kformula; screen.

&Ctrl;V Edit Paste

  Pastes the text you selected with Cut or Copy to the &kformula; screen.

&Ctrl;A Edit Select All

  Highlights all the text in the &kformula; screen for either Cut or Copy.

&Ctrl;R Edit Remove enclosing element

  Removes enclosing braces, brackets or absolute value bars. This action takes place on the braces just outside the cursor.

&Ctrl;G Edit Convert to Greek

  Converts a Latin character to a Greek symbol.

Edit Edit Formula String

  Brings up an editor where you can edit the existing formula.

See the Advanced editing section for details.

#### The Element Menu

&Ctrl;2 Element Add... Add root

  Inserts the square root.

&Ctrl;3 Element Add... Add fraction

  Inserts a fraction.

Element Add... Add bracket

  Inserts a pair of brackets, &ie; ( ). You can also just type ( to insert a pair of brackets.

&Ctrl;3 Element Add... Add fraction

  Inserts a fraction.

&Ctrl;6 Element Add... Add integral

  Inserts the integral sign.

&Ctrl;7 Element Add... Add sum

  Inserts the summation sign (sigma).

&Ctrl;4 Element Add... Add prod

  Inserts the product sign.

&Ctrl;8 Element Add... Add matrix

  Inserts a matrix. A dialog box pops up, with the default size being 3x3. You can specify the number of rows and columns in this box.

Element Add... Add 1x2 matrix

  Inserts a two rowed column vector.

&Ctrl;U Element Add... Add upper index

  Adds an upper index like so:

&Ctrl;L Element Add... Add lower index

  Adds a lower index:

  See the Definite Integrals and Indices section for details about indices.

Element Add... Add thin space

  Inserts a small space.

Element Add... Add medium space

  Inserts a space that is one and a half times wider.

Element Add... Add thick space

  Inserts a double space.

Element Add... Add quad space

  Inserts a quadruple wide space.

Element Matrix Insert Column

  Inserts a column in an existing matrix. The column is inserted where the cursor is at.

Element Matrix Append Column

  Appends a column to an existing matrix. The column is appended on the right.

Element Matrix Remove Column

  Removes a column from an existing matrix. Removal occurs where the cursor is positioned.

Element Matrix Insert Row

  Inserts a row in an existing matrix. The row is inserted where the cursor is at.

Element Matrix Append Row

  Appends a row to an existing matrix. The row is appended on the bottom.

Element Matrix Remove Row

  Removes a row from an existing matrix. Removal occurs where the cursor is positioned.

Element Left delimiter

  Allows insertion of various delimiters &ie; (, {, and [.

Element Right delimiter

  Allows insertion of various delimiters &ie; ), }, and ].

&Ctrl;I Element Insert symbol

  Inserts the symbol, selected in the symbol toolbar.

#### The Settings Menu

Here you can choose how &kformula; is configured. You can select the toolbars you want displayed or the type of fonts to be used.

Settings Syntax highlighting

  Checking this item determines if the numbers will be displayed in color

Settings Show file toolbar

  Toggles the toolbar that contains clickable icons for new, open and save files. Print and print preview are here also.

Settings Show edit toolbar

  Toggles the edit toolbar.Here are clickable icons for cut and paste as well as Undo and Redo.

Settings Show add toolbar

  This toolbar contains all the mathematical elements such as Sum, Integral, Exponent &etc;.

Settings Show symbol toolbar

  This toggles the combo box that contains Del, the partial derivative symbol, limit arrows, boolean operators and other mathematical symbols.

Settings Show matrix toolbar

  This toggles the matrix toolbar. It contains clickable icons that pertain to matrix creation and editing.

#### Configuring Shortcuts

The Settings Configure Shortcuts... allows you to specify shortcuts.

Below is an example of how to configure a shortcut for making a thick space.

Picture of shortcut dialog

- Click on the custom button.

- Next click on the primary button.

- Do `&Ctrl;Space` and the dialog should disappear. The shortcut is now entered.

Picture of shortcut dialog

Pressing the keys `CTRLSpace` now produces a thick space.

#### Configuring Toolbars

The Settings Configure Toolbars... is used to add additional buttons to the toolbars.

Picture of toolbars dialog

- To add a button to the File toolbar,

  Picture of toolbars dialog

  make sure File <KOfficeShell> is displayed in the top combo box.

- Click on one of the items in the left hand pane. This item will now have a blue background showing that it has been selected.

- Next click on the Right arrow button to place it in the right pane.

- Click on `Apply` and then click on `OK`

The new Item should be in the toolbar.

#### Configuring &kformula;

The Settings Configure &kformula;... is where the font sizes are selected and additional fonts are installed.

- The Formula section allows you to select fonts and font highlight colors.

- The Fonts section allows you to install additional fonts. See the Additional Math Fonts section.

#### The Help Menu

&help.menu.documentation;

## Advanced Editing

### Name insertion

A special feature is the name insertion. The blue square you type into is actual a list. Furthermore, that list can contain other lists. When you type a backslash (`\`) you get a new empty list right away. But this one is special. It uses a different font and is meant to insert things like function names. There is, however, a second idea here. Your keyboard only has a limited number of keys. The wealth of mathematical symbols on the other side is overwhelming. To get one of those you can type its name and press the space key afterwards. The name you typed will be replaced by the symbol then. In this context, the Space key means get out of here, that is move the cursor to the containing list. The cursor will be positioned at the end of what you just entered but will also enclose part of the original formula, after pressing the space bar.

Another thing you might want to insert are spaces. We all know, printing formulae is all about the right spacing. And you can do just that using a name list.

Inside the blue square do: `\,SPACE` to get a small space.

Do: `\<Space` to get a medium space.

Do: `\;Space` to get a thick space.

Do: `\ quad Space` to get a quadruple wide space.

In the same way, specific mathematical symbols can be inserted. `\ oint Space` inserts the path integral about a closed contour. Below is the result of `\ oint Space`:

Picture of path integral

### Editing Formulas

The Edit Edit Formula String allows the user to edit the ASCII formulas that have been copied from other applications, such as Scilab, and transform them directly into mathematical type. An example will make this clear. Below is a screenshot of `INRIA` Scilab.

Scilab picture

Copy and paste the text beginning with `x*sin(30*x)` into the formula editor as shown below:

Scilab formula edit picture

If you click on OK, the editor will complain about aborted parsing. It cannot recognize one of the symbols in the formula. The displayed formula would show that the Pi symbol is not correctly rendered. This means that the `%` must be deleted. Do this and &kformula; will render the mathematical font properly, as shown below.

Scilab formula rendered in &kformula;

The formula editor will accept most C language mathematical expressions, like the formulas from a Runge-Kutta program below:

    void derives(float x, float y[], float dydx[])
    {
     dydx[1] = y[2];
     dydx[2] = -0.8*x*y[2] - sin(x)*y[1];
    }

Here `dydx[1]` is the first order derivative and `dydx[2]` is the second order derivative. After copying the formula, you will have to edit the derivatives with &kformula;. Here is how it is done. First copy and paste the bottom expression into the formula editor.

Runge-Kutta in editor;

Next remove the `[ ]`, leaving just y's.

Runge-Kutta edited

Now click OK and place the cursor by a `y` and delete it. Insert the appropriate symbols as shown below.

Runge-Kutta in &kformula;

Not every expression that &kformula; is capable of translates into a valid C expression. For example the superscript expression:

Superscript in &kformula;

is displayed as `()**()`, which is not a valid C statement for exponentiation. Similarly the 1 by 2 matrix displays as `()/()`. This is not a valid array in C.

### Definite Integrals and Indices

#### Definite Integrals

A definite integral is made by using &Ctrl;U for the upper limit of integration and &Ctrl;L for the lower limit of integration.

definite integral

Reposition the cursor in front of the integral after making the first of the limits.

#### Positioning Indices

The upper or lower index can be positioned by highlighting the desired text. In this example, an arrow is needed above the P, in dP. Using &Ctrl;U places the desired vector symbol in the wrong place; namely above the d.

The problem is solved by highlighting only the P in and then entering &Ctrl;U. Here is the correct result.

## Mathematical Fonts

It is highly recommended to use the bakoma Tex fonts found here:

http://www.ctan.org/tex-archive/fonts/cm/ps-type1/bakoma/ttf/

You need these fonts in particular: cmbx10, cmex10, cmmi10, cmr10, cmsy10, msam10 and msbm10. Install them into your system and make sure you have the install path set as a FontPath in your X11 configuration, then completely restart your X Server, if you use a display manager like kdm, you should also restart kdm. Pressing &Ctrl; &Alt; Backspace at the login should do the trick. If unsure, do a complete reboot.

You can also use the Esstix fonts. Only try the Esstix fonts if the above don't work. These fonts can be obtained from

http://www.w3.org/Amaya/Distribution/esstix.tar.gz

### Installing the fonts with &kcontrolcenter;

After downloading the fonts, install them into a folder called `esstix`. You can unpack them with the &kde; application &ark;. Right click on `esstix.tar.gz` and select Extract here.... Then start the &kde; font installer by going to the K menu and selecting the command Control Center System Font Installer You should get the following screen:

Picture of the &kde; font installer
Picture of the &kde; font installer

You will need to run the font installer with root privileges. Click on the button Administrator Mode and enter your root password. Click on the button Change Folder. This should bring up a pane from where you can select the folder your fonts are stored in. In this example they are stored in `/home/poincare/esstix`.

Picture of the &kde; font installer
Picture of the &kde; font installer

Click on the the folder `esstix` and then click on the OK button. You should obtain the following result.

Picture of font installer ready to install
Picture of font installer ready to install

Click on the top font entry. Holding down the &Shift; key, click on the last esstix font, at the bottom. Your selection should look like this.

Picture of the font installer installing
Picture of the font installer installing

You should use the native AFM files. Set up your Settings System as shown below. The Generate AFM's, with box should be unchecked:

Picture of settings tab
Picture of settings tab

Return to the Fonts tab. Click on the Install button. The fonts will install. After this you must click on the Apply button. The following dialog will appear:

Picture of &kcontrolcenter; applying the fonts
Picture of &kcontrolcenter; applying the fonts

Answer Yes to the Apply system changes now dialog. Installation of the Esstix fonts is complete.

### Additional Math Fonts

Additional math fonts can be installed with Settings Configure &kformula;... Math Fonts

Add math fonts;

First install the desired fonts with the Font Installer, in &kcontrolcenter;. This will make them available to your computer. Next enter the Math Fonts section and add them using the Right arrow, as shown above. The Euclid Symbol fonts, that were added above, are now available in the Insert Symbolcombo box.

## Credits and Licenses

&kformula; copyright Ulrich Küttler

Co-developer: Andrea Rizzi

Documentation copyright 2002 Jonathan Drews j.e.drews@att.net

&underFDL; &underGPL;

## Installation

### How to obtain &kformula;

&install.intro.documentation;

### Requirements

&kformula; is part of &koffice; on The &kformula; home page You must have &koffice; installed. &kformula; will not work without the rest of &koffice;

### Compilation and Installation

&install.compile.documentation;

### Configuration

Some fonts will not work with &kformula;. You will need to try several to achieve a satisfactory rendering.

&documentation.index;