# The &kformula; Handbook

Jonathan
Drews

    j.e.drews@att.net

Anne-Marie
Mahfouf

    annma@kde.org

Alfredo
Beaumont Sainz

    alfredo.beaumont@gmail.com

Ulrich
Küttler
Developer
2002
Jonathan Drews
2005
Anne-Marie Mahfouf
2006
Alfredo Beaumont Sainz
&FDLNotice;
2006-09-09
1.5.90

&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;

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

&Ctrl;S File Save

  Saves the document.

File Save As...

  Saves the document with a name you provide.

File Reload

  Reloads the more recently opened document.

File Import

  Imports formulas from other formats.

File Export

  Exports the current document in another format.

File Mail...

  Invokes &kmail; so you can email the file. The file is already attached to the email.

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

&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 Copy

  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

Element Add Add Root

  Inserts the square root.

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.

Element Add Add Integral

  Inserts the integral sign.

Element Add Add Sum

  Inserts the summation sign. (sigma).

Element Add Add Product

  Inserts the product sign.

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.

Element Add Add Overline

  Inserts an overline in this box.

Element Add Add Underline

  Inserts an underline in this box.

Element Add Add Multiline

  Inserts a new line each time you type Enter in the square.

&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 Negative Thin Space

  Inserts a small reduced space, here between the o and the e: .

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 Size

  Allows to set the size of the font (from 6 to 72).

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 Toolbars File (KFormula)

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

Settings Toolbars Edit (KFormula)

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

Settings Toolbars Add (KFormula)

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

Settings Toolbars Font (KFormula)

  This toolbar contains the font settings (size, bold, italic, &etc;).

Settings Toolbars Symbol (KFormula)

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

Settings Toolbars Matrix (KFormula)

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

Settings Syntax Highlighting

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

#### Configuring Shortcuts

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

Below is an example of how to configure a shortcut for a print preview.

Picture of shortcut dialog

- Click on Custom.

- Next click on the button Advanced >> and then Primary shortcut:.

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

Picture of shortcut dialog

Pressing the keys `&Ctrl;Space` now displays the print preview.

#### 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 <&koffice;> is displayed in the top combo box.

- Click on one of the items in the left hand pane. This item will now be highlighted to show 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 and font styles are selected.

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

#### The Help Menu

Help Tip of the Day

  Opens the Tip of the Day dialog which displays a random tip about &kformula;.

&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 bar afterwards. The name you typed will be replaced by the symbol then. In this context, the Space bar 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.

## Credits and Licenses

&kformula; Copyright by The KFormula Team

### &kformula; Developers (Alphabetically)

- Alfredo Beaumont Sainz alfredo.beaumont@gmail.com

- Ulrich Küttler

- Andrea Rizzi

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

Documentation copyright 2005 Anne-Marie Mahfouf annma@kde.org

Documentation copyright 2006 Alfredo Beaumont Sainz alfredo.beaumont@gmail.com

&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;

&documentation.index;