Author: Roland Stroethoff, Klaas Freitag

# Das Kraft Handbuch

Roland Stroethoff, Klaas Freitag

## Einführung

Kraft ist ein Desktop Programm zum Organisieren von Bürodokumenten wie Angeboten und Rechnungen in kleinen Unternehmen. Es erleichtert die Erstellung der Dokument und vereinfacht wiederkehrende Aufgaben.

Mit Kraft wird kein Textbearbeitungsprogramm mehr benötigt. Rechnungs- und Angebotsdokumente werden mit ein paar Klicks erstellt und automatisch abgelegt. Kraft generiert hochqualitative PDF Dokumente für Druck, EMail und Archivierung.

Funktionen

  - Einfache, effiziente und hübsche Oberfläche.

  - Efficient creation of offers, invoices and similar documents.

  - Kundenverwaltung, durch die Verwendung von KAdressbuch gut in die KDE Infrastruktur integriert.

  - Verwaltung der Dokument-Beziehungen, zum Beispiel Teilrechnungen und Abschluß-Rechnungen oder Rechnungen aus Angeboten teil-automatisch erstellt.

  - Vorlagen für Dokument-Kopf- und Fusstexte sowie Dokumentposten.

  - Kataloge von Posten-Vorlagen zur Wiederverwendung.

  - Kalkulation von einzelnen Posten.

  - Einfache Materialverwaltung.

  - Konfigurierbare Dokument-Erstellung im PDF Format zum Druck und Versenden per Email incl. EPC QR Code.

  - Unterstützung für EPC QR-Code und XRechnung

Der Quelltext zu Kraft ist open source and wird unter der Lizenz GNU General Public License veröffentlicht.

Anmerkung | Kraft wird durch eine Gemeinschaft von Benutzern, Entwicklern und anderen vorangetrieben. Dieses Benutzerhandbuch benötigt Ihre Hilfe zur Verbesserung. Lernen Sie mehr auf how to contribute!

## Erster Start und Grundkonfiguration

Wenn Kraft das erste Mal gestartet wird, wird automatisch mit der Einrichtung begonnen.

Während des initialen Setup wird der Datenbank-Typ und die Adresse der Firma abgefragt.

You can fill in your company address (that appears on the printed documents) in two ways: in the setup procedure use the first tab Select from Addressbook for to select your own address in KAddressBook. For that there must be an entry of your own address in the address book. Alternatively the second tab Manual entry can be used to fill in the information of the address of your company manually. This step is necessary for the correct generation of your documents as the address is automatically used in the document generation step.

To generate the EPC QR Code that can be printed on the output document, the bank account details need to be added as well.

After the initial setup, select Preferences › Settings. That allows to prepare Kraft correctly for individual needs.

In the Preferences dialog we have the tabs:

    *Dokument Voreinstellungen
    *Steuern
    *Dokumenttypen
    *Stundensätze
    *Einheiten
    *die eigene Identität

Each of the tabs allows to enter useful values for the specific use case.

### Dokumenttypen

Beim ersten Start finden sich folgende Dokumenttypen:

- Auftragsbestätigung

- Lieferschein

- Rechnung

- Angebot

Translate this types to your own language. You can also add new ones and remove document types you won’t use.

#### Nummernkreise

Each document has to have an unique identifier that identifies the document. There must not be two documents in Kraft with the same identifier.

The format of the identifier is configuratable in Kraft. For that, Kraft has a concept of so called number cycles. Number cycles are used to define the form of the document number which is printed on every document.

All documents of a certain type have identifiers taken out of one number cycle. Each document type has a number cycle assigned. Different document types can use the same number cycle to generate ids from. That way, for example the document types Invoice and Final Invoice can use numbers from the same number cycle, even thought they are different document types in Kraft. Number cycles are identified by their name. User can create new number cycles and edit them clicking on the button Edit Number Cycles…​

The format of the document numbers can be customized by a template. A template can contain normal characters and also some variables that are replaced by the respective values when the document is created.

Each document number needs to be unique, and thus has to contain a counter. Kraft supports two types of counters: One (variable `%i`) is incremented globally for every new document. The other (variable `%n`) is reset every day and starts at 1 again on every new day. In addition to the counter, more information can be added to the template form an useful number. Examples are a constant text or parts of the date.

The default numbercycle delivered with Kraft contains the year, the month and a serial number. That way you can compare offers or orders from last year with this year or the month April of last year with the month April of this year and get on this way an impression from the results of your business.

Folgende Variablen stehen zur Verfügung:

`%y` or `%yyyy` | the year of the document date.
`%yy` | the year of the document (two digits).
`%w` | the week number of the document date.
`%ww` | the week number of the document date with leading zero.
`%d` | the day number of the document date.
`%dd` | the day number of the document date with leading zero.
`%m` or `%M` | the month number of the document date.
`%MM` | the month number with leading zero.
`%c` | the customer id from kaddressbook
`%type` | the localised doc type (offer, invoice etc.)
`%uid` | the contact id of the client.
`%i` .. `%iiiiii` | the unique counter
`%n` .. `%nnnnnn` | the unique day counter (combine with date)

A number cycle format template needs to contain either `%i` or `%n`, if not, `%i` is appended automatically.

Both `%i` and `%n` are numeric values. They can also be padded with with leading zeros. The length is defined by the number of i’s or n’s put into the template. For example, if a daily counter with length of three and leading zeros is desired, `%nnn` has to be put into the template. This works up to a length of six characters.

> Anmerkung | The "design" of the numbercycles and document numbers is very important. With the flexible system of templating Kraft can not prevent invalid number cycles. It is in the responsibility of the user.

#### PDF Template

In the entry field Template File: the user can select a custom template for this specific document type.

If the file extension of the template file is `.trml`, the ReportLab based document converter is used. If the file extension is `.gtmpl`, Kraft automatically uses the Weasyprint based converter which is default from Kraft 2.0.

> Anmerkung | The ReportLab system for PDF creation is deprecated in Kraft. Please, for new templates, always use Grantlee- and Weasyprint based templates.

#### PDF Postprocessing

After Kraft has created the PDF document it is possible to merge the created PDF with static, customized PDFs created by the user. With that, it is easy to add a custom stationery with a logo to the resulting PDF ("Watermark").

The static PDFs should have the same page size as the generated documents. Keep in mind to use optimized images for logos etc. when preparing the watermark PDF to not blow up the size of the result document.

The watermark options are:

1. No Watermark: No watermark is created

2. On first page: The first page of the watermark.pdf is merged with the first page of the result document

3. Watermark on all pages: Merges the first page of the watermark PDF to all pages of the result document

4. alternating: For this, the watermark PDF needs to have three pages. The first page is merged to the first page of the result document, the second and third page are alternated merge to subsequent pages.

5. different first and last page: the PDF needs to have three pages. The first page is merged to the first page of the result document, the third page to the last, and the second to all page between first and last page.

If there is another static PDF document put into the entry field "Append PDF:", it is appended to the generated PDF. With that, Kraft will automatically add for example terms and conditions documents to the final document.

### Steuern

In many countries there are two kinds of VAT-taxes for sold products.

Ein hoher und ein niedriger Steuersatz.

Fill here the appropriate amounts in for the high level and the low level. If the tax-level is changing, then you add here the start date with the new tax-levels.

### Wages

A list of wage costs is maintained in Kraft. The items are used in item templates during calculation.

All data can be edited, customized and new items can be added in the Kraft Configuration Dialog reachable through the Settings menu.

Remember that these units are later used in the documents, it is therefore important that you translate them to your own language and to fill in the correct prices.

### Units of measurement

A list of units of measurement is maintained in Kraft. In Kraft Configuration Dialog reachable through the Settings menu can you edit and customize items already in the list, and also can you add new items to the list.

Remember that these units are later used in the documents, it is therefore important that you translate them to your own language.

### Own identity

Check here if the information that you have given during the initial setup is correct for the use in the documents.

> Warnung | If you made the choice to use the information from KaddressBook then is the information from a later manual entry ignored.

After the configuration is finalized, we go back to the main window which consists of the three main tabs:

- Documents

- Timeline

- Catalogs

## Catalogs

Kraft supports so called Catalogs in which templates for document items are kept. With the catalogs creating documents can be significantly accelerated in the day to day business. When creating new documents, the items templates from the catalogs can easily selected and moved over to the document.

Since templates are organized in chapters entire documents can be prepared in different chapters to be used as template documents.

Of course the items in the documents can be edited after they got picked from a catalog.

By default Kraft comes with two different catalogs:

`Material`

A catalog of material that are sold, with their purchase prices, the profit and the sell-price.

and `Standard Templates`

A catalog of standard recipes of work like planting trees.

Both catalogs can have chapters and sub-chapters for to organize your templates. First we are going to fill in the

### Material Catalog

A catalog of material that are sold, with their purchase prices, the profit and the sell-price. First we are going to add new chapters and subchapters.

#### New chapters

Select with the mouse the column-name `material`, select now in the context-menu [Add a sub chapter]

and add an extra chapter like `Trees`

#### New sub chapters

We are going to ad sub chapters in the map `Trees`. Select with the mouse the name of the chapter where you like to add a subchapter, select now in the context-menu [Add a sub chapter] and ad an extra subchapters like `Loaf trees` and `needle trees`. After adding the extra chapters and subchapters for dividing the material, we are going to add the material themself.

#### New template

Select with the mouse the name of the sub-chapter or chapter where you like to add a material. Select the sub map Loaf trees and select now in the context-menu

Add the extra materials `coconut tree`, `apple tree` and `pine-apple tree`.

Fill in the price that we have paid.

Fill in the profit that we want to have on the material

And fill in how much is in a packet.

After this we add also in the map 'Wood' a item for a 'support pole' for later use with its price.

Now we are going to:

### Standard Templates

This is a catalog of standard recipes of work like:

- planting trees

- cutting grass

- transport costs

- planting grass

- sowing grass-seed

We add here the standard work of planting a tree.

Select with the mouse the name of the chapter [Work] where you like to add the new template,

select now the context-menu [New template]

and the extra templates `Plant tree` and `cut grass`.

After we made the new template, a window opens with 4 tabs:

- Template

- Time calculation

- Fixkosten

- Material

First we go to the tab:

#### Template

We give here the name of the new standard template like `Plant tree`

> Warnung | be careful, this name is later used in the invoice

we select that this is per piece and that the margin is 8% and that the full VAT is applicable.

#### Time calculation

We fill here in a number of work with the time:

Tabelle 1. Spent time
Dig hole | 32 min. | worker
Place tree | 12 min. | worker
Fill hole | 17 min. | worker
give water | 5 min. | worker

The cost for worker which we have earlier filled in is now used.

> Anmerkung | in the invoice we see later only Plant tree, we will not see the parts dig hole,place tree,fill hole,give water

Now we go to the tab

#### Fixed costs

and fill in:

Tabelle 2. Fixed item
Transportcost | 35 euro | 1 pcs.

After this we go to the tab:

#### Material

Here we select next, after which the window [Add Material to Calculation] opens for a selection of material. We navigate to the map 'wood' where we select the 'support pole'.

Tabelle 3. Used materials
1 | support pole | 3,5 euro

We go now back to the first tab template

On the first tab [template], we can now see the overall cost per one unit

Click on [OK] for saving the result or on [cancel] for discarding the result.

We make a second template `cut grass`

we fill in `cut grass`, as unit we choose sm (square meter), on the second tab we fill in that we need 3 min per square meter.

Click on [OK] for saving the result or on [Cancel] for discarding the result.

### Header- and Footer Text Templates

Kraft supports text templates also for the header- and footer-text of documents. Each document type has it’s own set of text templates. To access them, open a document of a certain document type in edit mode and use the show templates to make the templates visible. In both the header- and footer-section the stored templates become visible.

Directly under the navigation pane on the right side of the window is a list of the names of the available templates. Clicking on one of the names in the list displays the text in the pane below.

Underneath there are buttons located with the following functions from left to right:

1. Add the template to the document: This button replaces the text of the document with the selected template.

2. Insert the template to the document: The selected template is inserted to the current place of the cursor in the document.

3. Create a new template: Opens a dialog to enter a complete new template for the current doc type.

4. Edit the current template: Opens the dialog to edit the currently selected template.

5. Delete the current template: Removes the template permanently from the list of available templates.

Anmerkung | Templates with the name Standard are the default templates for the document type. They are inserted automatically if a document of this type is created.

#### Macros

Both the header- and footer-templates can contain so called macros which are replaced with calculated values once the document is rendered to the final output format.

The following list of macros are supported:

- `DATE_ADD_DAYS(<amount_days>)`: Returns the date of the of document plus the number of days specified as parameter to the macro.

- `ITEM_COUNT_WITH_TAG(<tag>)`: Returns the amount of items tagged with the tag.

- `NETTO_SUM_PER_TAG(<tag>)`: Returns the netto sum of all items that are tagged with the named tag.

- `BRUTTO_SUM_PER_TAG(<tag>)`: Returns the brutto sum of all items that are tagged with the named tag.

- `VAT_SUM_PER_TAG(<tag>)`: Returns the pure tax of all items that are tagged with the named tag.

- `IF_ANY_HAS_TAG(<tag>)` and `END_HAS_TAG`: Includes the text between the two macros only if there is at least one item that is tagged with the tag.

As an example, this footer text template can be used to automatically generate useful texts:

    Please pay this invoice until three weeks after the date of the document, which is the DATE_ADD_DAYS(21).

    IF_ANY_HAS_TAG(Material)
    This invoice lists material in ITEM_COUNT_WITH_TAG(Material) items. The net value is NETTO_SUM_PER_TAG(Material),
    plus VAT_SUM_PER_TAG(Material) = BRUTTO_SUM_PER_TAG(Material).
    END_HAS_TAG

We are now ready for the first invoice.

## Creating Documents

### The first Invoice

Open the tab documents

Click on create document

The window document [creation wizard opens].

Select in document type `invoice`.

Fill in on the whiteboard content a short text about what the invoice is, like: `cut grass and planted tree for mister Jonson`

Click on next

Select on the new window the name and address from the client.

(if the name and address is not there, click then on new contact or on edit contact if you want to edit the contact)

Click on OK.

Now opens the window document [items].

this window has 2 tabs and the 3 buttons on the top:

- Add item…​,

- Add discount item,

- Show templates.

In the left tab you can see all the items that we want to place on the invoice, on the right tab we see the text from the header, the total price and the footer.

If you click on the text of the header or the footer on the right side then the window changes in such a way that you can edit the header or the footer.

Adapt the header and the footer to your situation, on the footer you can place a text: `We make your garden-dream come to reality.`.

Click on the button Show templates.

The right tab changes and show now the earlier made templates, we select in the group Work, the subgroup Plant tree and click then on the button with the to the left pointing arrow on the bottom side.

A new window [Create Item from Template] opens.

Because we have planted 2 trees, we go to the field [insert] and change this to 2 pcs.

Click on OK for saving the result or on cancel for discarding the result.

The window close and we go back to the main window.

We click again on Show templates and select this time `cut grass`, we click again on the button with the arrow, in the opened window we select that the grass-field was 24 square meter.

Click on OK for saving the result or on Cancel for discarding the result.

We add now manually an item by clicking on the button Add item… and the window [create new item] opens.

Because we have delivered a special tree, we fill here in the name of the special tree `liguster`, at the field insert we fill in the number of the special trees that we have delivered and the price of them.

> Warnung | Remind that in the catalog we can add a profit on the price of the material, in the invoice and in the offer we can not add a profit on the price of the material.

We have now an invoice with 3 items.

Click on OK for saving the invoice or on Cancel for discarding the invoice.

We click on OK and save the result.

Your first invoice is now ready for sending.

In the window documents we see our first invoice, notice that this document has a document number which we can see on the left side.

On top of the window with all the invoices we see the button [Print Document], on which we click.

From the invoice will now a PDF be made which we can print on paper or send by email to the client.

After this we are going to create a offer for some work in a garden.

### Creating an Offer

The client has asked to plant a tree, we will offer 3 different trees which we can plant.

Beside this, we have seen that there is a lifeless three, which we will offer to remove as extra work.

For the total price we do not want to show the price of the removal of the lifeless tree and we want for the total price only to show the price of one tree and not three.

Open again the tab documents.

Click on create document

The window Document Creation Wizard opens.

select in document type > Offer.

Fill in on the whiteboard content a short text about what the offer is, like: `plant one tree and removal of lifeless tree`

Click on next

Select on the new window the name and address from the client.

(if the name and address is not there, click then on new contact or on edit contact if you want to edit the contact)

Click on OK.

Now the window [edit document] opens.

This window has 2 tabs and the 3 buttons on the top:

- Add item…​,

- Add discount item,

- Show templates.

Click on the button Show templates.

The right tab changes and show now the earlier made templates, we select in the group `Work`, the subgroup `Plant tree` and click then on the button with the to the left pointing arrow on the bottom side.

A new window [Create Item from Template] opens.

Because we want to plant 1 tree, we go to the field [insert] and keep this on 1 pcs.

Click on OK for saving the result or on Cancel for discarding the result.

The window close and we go back to the main window.

We click on the button Show templates and this time we select in catalog Material

The material-catalog opens, and we can select in the chapter `trees` the subchapter `loaf trees` in which we select the `apple tree` which we made earlier.

Click on we OK for saving the result or on cancel for discarding the result.

The window close and we go back to the main window.

We add now manually an item by clicking on the button `Add item…`.

the window [create new item] opens.

We want that the client can make a choice from an apple, a pear tree and the liguster.

Therefore we are going to add also a pear tree manually.

We click on the button Add item… and the window [create new item] opens.

We fill here in the name of the tree `Pear tree`, at the field insert we fill in the number of the special trees that we have delivered and the price of them.

We want add this to the material catalog for future use, therefore we select also [select this item as template for future documents] and we select in `trees`.

Click on OK for saving the result or on Cancel for discarding the result.

We does this again but then for the liguster.

We have now 3 items with trees in the offer.

As last item we add an item with `remove tree` with 0,5 hour for 32 euro.

On the left side of an item we can see 2 buttons:

a button with a flag and a button with what looks like a page.

We select the upper button with the page after which opens a context-menu with the items:

    [Item kind]->[Normal]
    [Item kind]>[Alternative]
    [Item kind]>[On demand]
    [Tax]
    [Move up]
    [Move down]
    [Lock item]
    [Unlock item]
    [Delete item]

We choose here [Item kind] and change for `pear tree` from [normal] to [alternative].

We do this also for [liguster] and for [remove tree] we change this from [normal] to [on demand].

Click on OK for saving the result or on Cancel for discarding the result.

We want to see the result and therefore we click on the button [show document].

We see now that the prize of the pear tree, the liguster and the removal of the tree is not used for the total prize. When we are happy with the result, we can click on the button close after which we click on the button Print Document for making a PDF what we can print out or send to the client.

After your first invoice is now your first offer now also ready for sending.

### Creating an Acceptance of Order

The document type "Acceptance of Order" is sent subsequently to an offer.

When a client has made a request, we will send an offer in which we describe which items we will deliver. Hopefully the client will give an order for the work.

It is a good practice to respond on the order with an "Acceptance of order" in which we describe all the items we will deliver. We can make the "Acceptance of order" on the same way as we made the invoice or the offer by selecting each item and correcting the number of delivery. This takes time and we can make errors by forgetting items or filling an incorrect number.

It can be done quicker by selecting the offer in the list and selecting Create Followup Document from either the context menu or the main menu.

We have now in documenttype the choice from:

    [Acceptance of order]
    [Invoice]
    [Partial Invoice]
    [final Invoice]
    [Progress Payment Invoice]

We select here "Acceptance of order". We have now a copy from the offer as an Acceptance of order (do not forget to adapt Alternative Delivery items and on demand items.)

You can do this also for the creation of the invoice as a followup for Acceptance of order. Each document type has a specific list of follow up documents. It is a good practice to describe on the invoice precisely what was delivered.

## Address Books

For efficient usage of Kraft, the address management is very important. Contact information of customers and suppliers needs to be managed and used daily.

Kraft does not come with its own address book implementation, but uses an established and mature solution called KAddressbook which is provided as part of the PIM (Personal Information Management) software collection of KDE. Integration with KAddressBook is the recommendation and default of Kraft.

However, in some situations the KAddressBook Integration can not be set up. In that cases, Kraft can also read a address collection of a local directory. The directory can be set in the Kraft config file in group `[KraftV2]`, key `KraftV2AddressDir`. If not explicitly set, it defaults to `$HOME/.local/share/contacts`.

This directory needs to contain single files in the vCard format, with file extension `.vcf`. All these files are read and presented as addresses in Kraft.

> Anmerkung | Kraft does not alter the entries in the addressbook directory. It is accessed read only.

To edit addresses and add new ones, users can still use KAddressBook, which has support for local address books. It is also possible to synchronize addresses into a local directory from other remote address collections such as Google Addresses utilizing a tool like vdirsyncer.

## Customization

Kraft can be customized in most of the graphical user interface and in particular in the output it generates.

### Output Document Customization

To create PDF output documents, the document data that was edited in the Kraft app is filled into a template. The template defines how the output document looks like, ie. by font settings, placing of elements and such.

The file that is assembled from data and the template is converted to PDF using a special document creation script. All that is started automatically by Kraft if a document should be printed.

Each document type in Kraft can have it’s own template that is used to create a PDF. Which one can be set in the Settings dialog for document types.

#### WeasyPrint Documents

Anmerkung | Kraft still ships with the old ReportLab based converter, but that will be deprecated the future. The WeasyPrint based system is the future. It is a recommended to port existing templates.

With WeasyPrint Kraft uses a very powerful generator that makes it very easy to create highly customized documents with great quality.

WeasyPrint converts a html file to PDF. It is integrating a cascading stylesheet (CSS) file which has a huge impact on the PDF document’s look.

The html- and CSS input file for WeasyPrint is built from the Kraft template file.

To enable the use of WeasyPrint for a document type in Kraft, simply create a weasyprint compatible template file and save it with the extension .gtmpl. Based on the file extension Kraft automatically uses WeasyPrint and the Grantlee templating engine for rendering.

From version 0.95 on Kraft ships with an example template in the Grantlee- and WeasyPrint format. It can be found at `/usr/share/kraft/reports/invoice.gtmpl` or online on Github. An example CSS file `kraft.css` (on Github) is shipped as a good starting point for adoption.

#### Template Variables

To generate the PDF, Kraft has to transfer data from the document you have been working on to the input file that is processed to a PDF. For that, Kraft uses a text template in which Kraft replaces variables with the actual values.

For example, the tag `{{ doc.doctype }}` is replaced with the current document type during the generating process.

The syntax is based on the Django syntax for templates described in the the docs.

#### Adding a Logo

On the PDF output it is nice to have a logo image included, if the documents should not be printed on a prepared stationary that comes with a printed logo already.

This chapter describes a few methods to achieve that with the weasyprint based template.

##### PDF Watermark Functionality

The first, and easiest way to add a logo and other details on the print out is to use the so called PDF Watermark option.

That means that the generated document, which does not contain a logo at all, is merged with another PDF into one doc. The so called watermark feature requires an otherwise empty PDF page of the same size as your generated document, that has the logo printed at the right position. It can be created with a text processor that can export PDF.

In the Kraft doc type settings dialog, the watermark options for a specific doc type can be selected. The watermark PDF file can be selected and either be applied to the first page only, or to every page of the generated document.

Once set up, Kraft automatically merges the generated document with the watermark PDF. The result document contains the content of both documents merged together. This is not only useful for logos, but also other details in the document footer.

##### CSS Directives for Pages

The second option is to use the CSS directive for page content on printed HTML pages. This only works with weasyprint based doc generation.

It uses Cascading Style Sheet (CSS) directives for paged media. CSS uses the `@page` keyword to define attributes of the page on which the content is printed. Weasyprint makes heavy use of that, for example to define the page size.

In the Kraft default template for weasyprint called `invoice.gtmpl` this page section can be found:

    @page {
        size: A4;
        margin-left: 2.4cm;
        margin-top:27mm;
        margin-right: 1.6cm;
        margin-bottom: 2cm;
        color: #2f590a;
    }

which defines the page size to be A4, with the given margins and a default text color.

To add a logo on in the top left corner of the first page of the result doc, the following snippet could be added:

    @page :first {
      margin-top: 20mm;
      margin-bottom: 3cm;

      @top-left {
        content: url(/home/miller/miller_logo_s1.png);
        width:3cm;
        height: 1cm;
      }
    }

This displays the top left content only on the first page, and also assigns a different top- and bottom margin to the first page. Note that the content url in the example is a local path, but any valid URL can be used.

A more fine granular way of placing the logo can be achieved by placing an `img` tag into the template like this:

    <img id="logo" src="file:///path/to/your/logo.png" />

The CSS code to place the logo accordingly is like

    /*
     * Absolut positioned logo
     */
    img#logo {
      position: absolute;
      right: 0px;
      top: -100px;
      width: 178px;
      z-index: -1;
    }

With that, the logo is independent from the @page positioning from the first example.

#### EPC QR Code

With Weasyprint based PDF generation Kraft supports the EPC QR Code which implements a European standard for payments by computer and mobile devices.

In Germany it is also known as Giro Code, in Belgium as Bancontact QR, in the Netherlands as iDEAL QR-code and in Spain it is also known as Bizum QR-code.

To use the EPC QR code on the invoice printout, the bank account information has to be added to the own identity settings dialog in Kraft. The giro code is current only generated for documents with the document type `Rechnung`.

To include the generated EPC QR Code into the PDF document, the Weasyprint template needs to contain a snippet like this:

        {%if doc.isInvoice and epcqrcode.valid %}
        <p class="epcqrcode">
          <img class="epc" src="file://{{ epcqrcode.svgfilename }}" alt="EPC QR Code" />
          Dieser QR Code ermöglicht einfaches, sicheres und schnelles Begleichen dieser Rechnung via GiroPay:
          Diesen Code mit dem Smartphone scannen und Überweisung per Banking App aufgeben.
        </p>
        {% endif %}

## Menus and Shortcuts

### Main Application Menu

#### The File Menu

    [File]>[Quit]
    [Ctrl]+[Q]
    Quits the application.

#### The Document Menu

    [Document]>[Show Document]
    [Ctrl]+[R]
    Opens a window with the selected document for showing it.

    [Document]>[Edit Document]
    [Ctrl+O]
    Opens a window with the selected document for editing it.

    [Document]>[Open Archived document]
    [Ctrl]+[A]
    Opens an archived document.

    [Document]>[Create Document]
    Opens a window with a wizard for creating a new client-document.

    [Document]>[Copy Document]
    Makes a copy of the selected client-document to a new client-document
    which can belong to an other client or an other documenttype.

    [Document]>[Follow Document]
    Opens the selected client-document for editing.

    [Document]>[Print document]
    Makes a PDf from the selected client-document for to be mailed or
    printed.

    [Document]>[Mail document]
    [Ctrl]+[M]
    Mails a document.

#### The Settings menu

    [Settings]>[Edit Tag Templates]
    [Ctrl]+[E]
    Opens a window where you add, edit or translate the tags (like work,
    material, plants or discounts).

    [Settings]>[Redo initial setup]
    [Ctrl+R]
    Redoes the initial setup. After this, a restart of Kraft is required.

    [Settings]>[Showed toolbars]
    Here you can decide if the `main toolbar` and the toolbar `Document Actions`
    are shown.

    [Settings]>[Configure Kraft]
    [Ctrl]+[Shift]+[,]
    Here you can configure Kraft.

### Document Edit Window

#### The context Menu

     [Context]>[Item kind]
     change the status from this item between
    * Normal
    * Alternative
    * On demand

    [Context]>[Tax]
    Seems not working.

    [Context]>[Move up]
    Moves this item a place up in document.

    [Context]>[Move down]
    Moves this item a place down in document.

    [Context]>[Lock item]
    It is not clear what is does.

    [Context]>[Unlock item]
    It is not clear what is does.

    [Context]>[Delete item]
    Removes this item from document.

## Fortgeschrittene Themen

Dieses Kapitel beschreibt fortgeschrittene Themen um Kraft. Dabei wird etwas Linux-Kenntnis vorausgesetzt, und das Aufsetzen sollte von erfahreneren Linux Administratoren durchgeführt und gut testet werden.

### Using Kraft Collaboratively

Kraft kann kollaborativ in einer verteilten Umgebung verwendet werden. Das heisst, dass mehrere Benutzer an ihren jeweiligen Arbeitsplatzrechnern mit ihrer eigenen Kraft Instanz arbeiten können und dabei die selben Daten verwenden.

Das ganze Thema ist Veränderung unterworfen, da Kraft in naher Zukunft ownCloud als private Cloud Lösung zur Datenspeicherung verwenden wird.

#### Datenbank und Dokumentpool teilen

Der einfachste Fall ist das zwei oder wenige mehr Kraft Instanzen die Datenbank gemeinsam benutzen und den Pool von PDF Dokumenten gemeinsam verwenden. Um es einfach zu halten werden hier zwei Instanzen beschrieben.

Ein typischer Anwendungsfall könnte sein: Zwei verschiedene Linux user möchten Kraft verwenden. Sie haben beide ihren eigenen Computer und arbeiten im selben Netzwerk. Dieses Beispiel beschreibt eine Situation mit einem Hauptbüro das Kraft im normalen Modus betreibt, und einem Notebook mit Kraft, das im NurLesen Modus um Dokumente anzusehen, Kataloge zu überprüfen und ähnliches.

Dafür müssen die folgenden Voraussetzungen erfüllt sein:

1. Als Datenbank-Backend wird MySQL oder MariaDB verwendet. Sqlite wird nicht unterstützt.

2. Die Datenbank ist mit dem MySQL Benutzer von beiden Rechnern aus erreichbar.

3. Das Dokument-Speicher-Verzeichnis muss geteilt werden.

> Achtung: Es gibt keinen Schutz dagegen, dass beide Benutzer das gleiche Dokument zur gleichen Zeit bearbeiten. Weil das gefährlich ist und zu unvorhersehbaren Resultaten führen kann, ist es empfohlen, Kraft in allen ausser der Haupt-Instanz im Nur-Lese Modus zu betreiben. Der Nur-Lese Modus wird mit Krafts Kommandozeilenschalter -r eingeschaltet.

Sharing the Database

Der Datenbankserver sollte auf der Haupt-Maschine installiert sein, oder es sollte ein spezialisiertes Gerät wie ein NAS verwendet werden. Die Netzwerk Geschwindigkeit beeinflusst die Benutzbarkeit natürlich erheblich.

Howtos um MySQL aufzusetzen sind im Internet zu finden.

Sharing the Document Pool Directory

Kraft schreibt generierte PDFs in ein lokales Verzeichnis. Welches Verzeichnis das ist kann im Kraft Konfigfile eingerichtet werden. Das Konfigfile muss auf allen Instanzen angepasst werden.

Es ist in jedem Benutzer Homeverzeichnis unter dem releativen Pfad `.config/kraftrc`. Es muss den folgenden Konfigurations-Wert enthalten:

    [reporting]
    PdfOutputDir=/data/space/kraftdoc/pdf

Es gibt verschiedene Wege wie das Verzeichnis geteilt werden kann, zum Beispiel NFS und SMB Server. Es ist entscheidend, dass beide Benutzer von beiden Maschinen die Dateien auflisten und zugreifen können. Der Hauptbenutzer braucht Schreib- und Leserecht., Nur-Lese Bentuzer brauchen nur Lesezugriff auf die Dateien.

Ein empfohlenes Setup benutzt ein NFS Share über autofs, das auf der Hauptmaschine aufgesetzt werden muss. Um Dateizugriff zu verwalten, sollte eine Gruppe aufgesetzt werden.

Starting Kraft in read-only mode

Um Kraft im Nur-Lese Modus zu starten, muss das Programm mit dem Kommandozeilenschalter `-r` gestartet werden.

### XRechnung Support

Kraft supports the XRechnung standard. That is a digital format for electronic invoicing, and it passed as law in Germany and follows a EU directive. The XRechnung is a XML file format designed for that purpose.

To use the XRechnung Export productivly, a little manual work is still needed in Kraft. Kraft creates the XML file based on a template, very similar to the normal PDF documents. That means that it loads a template that contains static elements (ie. the company address) that do not change between different invoices. The dynamic elements (customer data, items etc.) are filled into the template during the generation step.

In order to generate correct XRechnung files for the specific company, the user has to adopt the template file manually to the companies needs. Note that this has only to be done once and should be easy for a person with a bit computer experience (Basic knowledge about XML appreciated!).

To adapt the file to the needs of the company, it is best to start with the example XRechnung file. It has to be downloaded and saved into a location that the user can edit. Open it in a normal text editor, such as Kate.

Read carefully through the file without being scared off by the XML format. All user strings (ie. company name, address and such) are user specific and should be replaced accordingly. Find details about the format here to better understand the meaning of the fields.

Make sure to not disturb the proper XML format and do not change places where the template format `{{ template_name }}` is used.

Once the file is adopted to the needs, open the Settings dialog of Kraft and insert the filename into the entry field for the XRechnung Template File on the Document Defaults page.

Next is to specify for which document types the XRechnung export should be made available. For that, open the Kraft Settings dialog, and proceed to the Document Type tab on the left. For each document type listed there, you can mark the checkbox Enable XRechnung Support.

After that steps, the Export XRechung menu item will let you open a dialog to add a few additional parameters for the XRechnung that Kraft does not have by default, and lets you pick a filename where to save the XRechnung invoice file to.

This file can now be transferred to the receiver of the invoice via email, a private file share or the like.

Anmerkung | There are validators for invoices in XRechnung format out there in the internet. It is useful to verify the format of the Kraft exported XRechnung.

### Changing the Locale

If it is needed that Kraft runs under a different locale than the actual desktop environment, this can be achieved by setting the desired locale in the start file of Kraft.

On the linux desktop, apps are usually started through a so called desktop file. It contains the information how the Kraft binary is started if user clicks on the icon on the desktop or in the start menu.

The desktop file can usually be found in `/usr/share/applications/de.volle-kraft-voraus.kraft.desktop`.

It contains the line

    Exec=kraft %u

which starts the application with the default locale.

Changing it to

    Exec=env LANG=de_DE.UTF-8 kraft %u

would change that to run in the German locale for example, independent from the desktop environment location.

## Credits und Lizenz

Program and documentation copyright 2004–2026 Klaas Freitag

Documentation copyright 2020-2026 Ronald Stroethoff