Rechtschreib- und Tippfehler in Doku
[kivitendo-erp.git] / doc / dokumentation.xml
1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <book id="kivitendo-documentation" lang="de">
5   <title>kivitendo 3.1.0: Installation, Konfiguration, Entwicklung</title>
6
7   <chapter id="Aktuelle-Hinweise">
8     <title>Aktuelle Hinweise</title>
9
10     <para>Aktuelle Installations- und Konfigurationshinweise gibt es:</para>
11
12     <itemizedlist>
13       <listitem>
14         <para>im kivitendo-Forum: <ulink
15         url="https://forum.kivitendo.org/">https://forum.kivitendo.org/</ulink></para>
16       </listitem>
17       <listitem>
18         <para>in der doc/UPGRADE Datei im doc-Verzeichnis der Installation</para>
19       </listitem>
20       <listitem>
21         <para>Im Schulungs- und Dienstleistungsangebot der entsprechenden kivitendo-Partner: <ulink
22         url="http://www.kivitendo.de/partner.html">http://www.kivitendo.de/partner.html</ulink></para>
23       </listitem>
24     </itemizedlist>
25   </chapter>
26
27   <chapter id="config">
28     <title>Installation und Grundkonfiguration</title>
29
30     <sect1 id="Installation-Übersicht">
31       <title>Übersicht</title>
32
33       <para>
34         Die Installation von kivitendo umfasst mehrere Schritte. Die folgende Liste kann sowohl für Neulinge als auch für alte Hasen als
35         Übersicht und Stichpunktliste zum Abhaken dienen, um eine Version mit minimalen Features möglichst schnell zum Laufen zu kriegen.
36       </para>
37
38       <orderedlist>
39         <listitem><para><emphasis>Voraussetzungen überprüfen</emphasis>: kivitendo benötigt gewisse Ressourcen und benutzt weitere
40         Programme. Das Kapitel "<xref linkend="Benötigte-Software-und-Pakete"/>" erläutert diese. Auch die Liste der benötigten Perl-Module
41         befindet sich hier.</para></listitem>
42
43         <listitem><para><emphasis>Installation von kivitendo</emphasis>: Diese umfasst die "<xref
44         linkend="Manuelle-Installation-des-Programmpaketes"/>" sowie grundlegende Einstellungen, die der "<xref
45         linkend="config.config-file"/>" erläutert.</para></listitem>
46
47         <listitem><para><emphasis>Konfiguration externer Programme</emphasis>: hierzu gehören die Datenbank ("<xref
48         linkend="Anpassung-der-PostgreSQL-Konfiguration"/>") und der Webserver ("<xref
49         linkend="Apache-Konfiguration"/>"). </para></listitem>
50
51         <listitem><para><emphasis>Benutzerinformationen speichern können</emphasis>: man benötigt mindestens eine Datenbank, in der
52         Informationen zur Authentifizierung sowie die Nutzdaten gespeichert werden. Wie man das als Administrator macht, verrät "<xref
53         linkend="Benutzerauthentifizierung-und-Administratorpasswort"/>".</para></listitem>
54
55         <listitem><para><emphasis>Benutzer, Gruppen und Datenbanken anlegen</emphasis>: wie dies alles zusammenspielt erläutert "<xref
56         linkend="Benutzer--und-Gruppenverwaltung"/>".</para></listitem>
57
58         <listitem><para><emphasis>Los geht's</emphasis>: alles soweit erledigt? Dann kann es losgehen: "<xref
59         linkend="kivitendo-ERP-verwenden"/>"</para></listitem>
60       </orderedlist>
61
62       <para>
63         Alle weiteren Unterkapitel in diesem Kapitel sind ebenfalls wichtig und sollten vor einer ernsthaften Inbetriebnahme gelesen
64         werden.
65       </para>
66     </sect1>
67
68     <sect1 id="Benötigte-Software-und-Pakete">
69       <title>Benötigte Software und Pakete</title>
70
71       <sect2 id="Betriebssystem">
72         <title>Betriebssystem</title>
73
74         <para>kivitendo ist für Linux konzipiert, und sollte auf jedem
75         unixoiden Betriebssystem zum Laufen zu kriegen sein. Getestet ist
76         diese Version im speziellen auf Debian und Ubuntu, grundsätzlich wurde
77         bei der Auswahl der Pakete aber darauf Rücksicht genommen, dass es
78         ohne große Probleme auf den derzeit aktuellen verbreiteten
79         Distributionen läuft.</para>
80
81         <para>Anfang 2014 sind das folgende Systeme, von denen bekannt ist,
82         dass kivitendo auf ihnen läuft:</para>
83
84         <itemizedlist>
85
86           <listitem>
87             <para>Debian</para>
88             <itemizedlist>
89                <listitem>
90                  <para>6.0 "Squeeze" (hier muss allerdings das Modul FCGI in der Version >= 0.72 compiled werden, und <literal>Rose::DB::Object</literal> ist zu alt)</para>
91                </listitem>
92                <listitem>
93                  <para>7.0 "Wheezy"</para>
94                </listitem>
95             </itemizedlist>
96           </listitem>
97
98           <listitem>
99             <para>Ubuntu 12.04 LTS "Precise Pangolin", 12.10 "Quantal Quetzal", 13.04 "Precise Pangolin" und 14.04 "Trusty Tahr" LTS Alpha</para>
100           </listitem>
101
102           <listitem>
103             <para>openSUSE 12.2, 12.3 und 13.1</para>
104           </listitem>
105
106           <listitem>
107             <para>SuSE Linux Enterprice Server 11</para>
108           </listitem>
109
110           <listitem>
111             <para>Fedora 16 bis 19</para>
112           </listitem>
113         </itemizedlist>
114       </sect2>
115
116       <sect2 id="Pakete" xreflabel="Pakete">
117         <title>Benötigte Perl-Pakete installieren</title>
118
119         <para>Zum Betrieb von kivitendo werden zwingend ein Webserver (meist
120         Apache) und ein Datenbankserver (PostgreSQL, mindestens v8.4)
121         benötigt.</para>
122
123         <para>Zusätzlich benötigt kivitendo einige Perl-Pakete, die nicht Bestandteil einer Standard-Perl-Installation sind. Um zu
124         überprüfen, ob die erforderlichen Pakete installiert und aktuell genug sind, wird ein Script mitgeliefert, das wie folgt aufgerufen
125         wird:</para>
126
127         <programlisting>./scripts/installation_check.pl</programlisting>
128
129         <para>Die vollständige Liste der benötigten Perl-Module lautet:</para>
130
131         <itemizedlist>
132           <listitem><para><literal>parent</literal> (nur bei Perl vor 5.10.1)</para></listitem>
133
134           <listitem><para><literal>Archive::Zip</literal></para></listitem>
135
136           <listitem><para><literal>Config::Std</literal></para></listitem>
137
138           <listitem><para><literal>DateTime</literal></para></listitem>
139
140           <listitem><para><literal>DBI</literal></para></listitem>
141
142           <listitem><para><literal>DBD::Pg</literal></para></listitem>
143
144           <listitem><para><literal>Email::Address</literal></para></listitem>
145
146           <listitem><para><literal>Email::MIME</literal></para></listitem>
147
148           <listitem><para><literal>FCGI</literal> (nicht Versionen 0.68 bis 0.71 inklusive; siehe <xref linkend="Apache-Konfiguration.FCGI.WebserverUndPlugin"/>)</para></listitem>
149
150           <listitem><para><literal>File::Copy::Recursive</literal></para></listitem>
151
152           <listitem><para><literal>JSON</literal></para></listitem>
153
154           <listitem><para><literal>List::MoreUtils</literal></para></listitem>
155
156           <listitem><para><literal>Net::SMTP::SSL</literal> (optional, bei E-Mail-Versand über SSL; siehe Abschnitt "<xref
157           linkend="config.sending-email.smtp"/>")</para></listitem>
158
159           <listitem><para><literal>Net::SSLGlue</literal> (optional, bei E-Mail-Versand über TLS; siehe Abschnitt "<xref
160           linkend="config.sending-email.smtp"/>")</para></listitem>
161
162           <listitem><para><literal>Params::Validate</literal></para></listitem>
163
164           <listitem><para><literal>PDF::API2</literal></para></listitem>
165
166           <listitem><para><literal>Rose::Object</literal></para></listitem>
167
168           <listitem><para><literal>Rose::DB</literal></para></listitem>
169
170           <listitem><para><literal>Rose::DB::Object</literal> Version 0.788 oder neuer</para></listitem>
171
172           <listitem><para><literal>Template</literal></para></listitem>
173
174           <listitem><para><literal>Text::CSV_XS</literal></para></listitem>
175
176           <listitem><para><literal>Text::Iconv</literal></para></listitem>
177
178           <listitem><para><literal>URI</literal></para></listitem>
179
180           <listitem><para><literal>XML::Writer</literal></para></listitem>
181
182           <listitem><para><literal>YAML</literal></para></listitem>
183         </itemizedlist>
184
185         <para>Seit v3.0.0 sind die folgenden Pakete hinzugekommen: <literal>File::Copy::Recursive</literal>.</para>
186
187         <para>Seit v2.7.0 sind die folgenden Pakete hinzugekommen: <literal>Email::MIME</literal>, <literal>Net::SMTP::SSL</literal>,
188         <literal>Net::SSLGlue</literal>.</para>
189
190         <para>Gegenüber Version 2.6.0 sind zu dieser Liste 2 Pakete
191         hinzugekommen, <literal>URI</literal> und
192         <literal>XML::Writer</literal> sind notwendig. Ohne startet kivitendo
193         nicht.</para>
194
195         <para>Gegenüber Version 2.6.1 sind <literal>parent</literal>,
196         <literal>DateTime</literal>, <literal>Rose::Object</literal>,
197         <literal>Rose::DB</literal> und <literal>Rose::DB::Object</literal>
198         neu hinzugekommen. <literal>IO::Wrap</literal> wurde entfernt.</para>
199
200         <para>Gegenüber Version 2.6.3 ist <literal>JSON</literal> neu
201         hinzugekommen.</para>
202
203         <para><literal>Email::Address</literal> und
204         <literal>List::MoreUtils</literal> sind schon länger feste
205         Abhängigkeiten, wurden aber bisher mit kivitendo mitgeliefert. Beide
206         sind auch in 2.6.1 weiterhin mit ausgeliefert, wurden in einer
207         zukünftigen Version aber aus dem Paket entfernt werden. Es wird
208         empfohlen diese Module zusammen mit den anderen als Bibliotheken zu
209         installieren.</para>
210
211         <sect3>
212           <title>Debian und Ubuntu</title>
213
214           <para>Alle benötigten Perl-Pakete stehen für Debian und Ubuntu als Debian-Pakete zur Verfügung. Sie können mit folgendem Befehl
215           installiert werden:</para>
216
217           <programlisting>apt-get install apache2 libarchive-zip-perl libclone-perl \
218   libconfig-std-perl libdatetime-perl libdbd-pg-perl libdbi-perl \
219   libemail-address-perl  libemail-mime-perl libfcgi-perl libjson-perl \
220   liblist-moreutils-perl libnet-smtp-ssl-perl libnet-sslglue-perl \
221   libparams-validate-perl libpdf-api2-perl librose-db-object-perl \
222   librose-db-perl librose-object-perl libsort-naturally-perl \
223   libstring-shellquote-perl libtemplate-perl libtext-csv-xs-perl \
224   libtext-iconv-perl liburi-perl libxml-writer-perl libyaml-perl \
225   libfile-copy-recursive-perl postgresql</programlisting>
226         </sect3>
227
228         <sect3>
229           <title>Fedora Core</title>
230
231           <para>Für Fedora Core stehen die meisten der benötigten Perl-Pakete als RPM-Pakete zur Verfügung. Sie können mit folgendem Befehl installeirt werden:</para>
232
233           <programlisting>yum install httpd perl-Archive-Zip perl-Clone perl-DBD-Pg \
234   perl-DBI perl-DateTime perl-Email-Address perl-Email-MIME perl-FCGI \
235   perl-File-Copy-Recursive perl-JSON perl-List-MoreUtils perl-Net-SMTP-SSL perl-Net-SSLGlue \
236   perl-PDF-API2 perl-Params-Validate perl-Rose-DB perl-Rose-DB-Object \
237   perl-Rose-Object perl-Sort-Naturally perl-String-ShellQuote \
238   perl-Template-Toolkit perl-Text-CSV_XS perl-Text-Iconv perl-URI \
239   perl-XML-Writer perl-YAML perl-parent postgresql-server</programlisting>
240
241           <para>Zusätzlich müssen einige Pakete aus dem CPAN installiert werden. Dazu können Sie die folgenden Befehle nutzen:</para>
242
243           <programlisting>yum install perl-CPAN
244 cpan Config::Std</programlisting>
245
246         </sect3>
247
248         <sect3>
249           <title>openSUSE</title>
250
251           <para>Für openSUSE stehen die meisten der benötigten Perl-Pakete als RPM-Pakete zur Verfügung. Sie können mit folgendem Befehl
252           installiert werden:</para>
253
254           <programlisting>zypper install apache2 perl-Archive-Zip perl-Clone \
255   perl-Config-Std perl-DBD-Pg perl-DBI perl-DateTime perl-Email-Address \
256   perl-Email-MIME perl-FastCGI perl-File-Copy-Recursive perl-JSON perl-List-MoreUtils \
257   perl-Net-SMTP-SSL perl-Net-SSLGlue perl-PDF-API2 perl-Params-Validate \
258   perl-Sort-Naturally perl-Template-Toolkit perl-Text-CSV_XS perl-Text-Iconv \
259   perl-URI perl-XML-Writer perl-YAML postgresql-server</programlisting>
260
261           <para>Zusätzlich müssen einige Pakete aus dem CPAN installiert werden. Dazu können Sie die folgenden Befehle nutzen:</para>
262
263           <programlisting>yum install perl-CPAN
264 cpan Rose::Db::Object</programlisting>
265
266         </sect3>
267       </sect2>
268     </sect1>
269
270     <sect1 id="Manuelle-Installation-des-Programmpaketes"
271            xreflabel="Manuelle Installation des Programmpaketes">
272       <title>Manuelle Installation des Programmpaketes</title>
273
274       <para>Die kivitendo ERP Installationsdatei (<filename>kivitendo-erp-3.1.0.tgz</filename>) wird im Dokumentenverzeichnis des Webservers
275       (z.B.  <filename>/var/www/html/</filename>, <filename>/srv/www/htdocs</filename> oder <filename>/var/www/</filename>) entpackt:</para>
276
277       <programlisting>cd /var/www
278 tar xvzf kivitendo-erp-3.1.0.tgz</programlisting>
279
280       <para>Wechseln Sie in das entpackte Verzeichnis:</para>
281
282       <programlisting>cd kivitendo-erp</programlisting>
283
284       <para>Alternativ können Sie auch einen Alias in der
285       Webserverkonfiguration benutzen, um auf das tatsächliche
286       Installationsverzeichnis zu verweisen.</para>
287
288       <para>Die Verzeichnisse <filename>users</filename>, <filename>spool</filename> und <filename>webdav</filename> müssen für den Benutzer
289       beschreibbar sein, unter dem der Webserver läuft. Die restlichen Dateien müssen für diesen Benutzer lesbar sein. Die Benutzer- und
290       Gruppennamen sind bei verschiedenen Distributionen unterschiedlich (z.B. bei Debian/Ubuntu <constant>www-data</constant>, bei Fedora
291       core <constant>apache</constant> oder bei OpenSUSE <constant>wwwrun</constant>).</para>
292
293       <para>Der folgende Befehl ändert den Besitzer für die oben genannten
294       Verzeichnisse auf einem Debian/Ubuntu-System:</para>
295
296       <programlisting>chown -R www-data users spool webdav</programlisting>
297
298       <para>Weiterhin muss der Webserver-Benutzer in den Verzeichnissen <filename>templates</filename> und <filename>users</filename>
299       Unterverzeichnisse für jeden neuen Benutzer anlegen dürfen, der in kivitendo angelegt wird:</para>
300
301       <programlisting>chown www-data templates users</programlisting>
302     </sect1>
303
304     <sect1 id="config.config-file">
305       <title>kivitendo-Konfigurationsdatei</title>
306
307       <sect2 id="config.config-file.introduction"
308              xreflabel="Einführung in die Konfigurationsdatei">
309         <title>Einführung</title>
310
311         <para>In kivitendo gibt es nur noch eine Konfigurationsdatei,
312         die benötigt wird: <filename>config/kivitendo.conf</filename> (kurz:
313         "die Hauptkonfigurationsdatei"). Diese muss bei der Erstinstallation
314         von kivitendo bzw. der Migration von älteren Versionen angelegt
315         werden.</para>
316
317         <para>Als Vorlage dient die Datei
318         <filename>config/kivitendo.conf.default</filename> (kurz: "die
319         Default-Datei"):</para>
320
321         <programlisting>$ cp config/kivitendo.conf.default config/kivitendo.conf</programlisting>
322
323         <para>Die Default-Datei wird immer zuerst eingelesen. Werte, die in
324         der Hauptkonfigurationsdatei stehen, überschreiben die Werte aus der
325         Default-Datei. Die Hauptkonfigurationsdatei muss also nur die
326         Abschnitte und Werte enthalten, die von denen der Default-Datei
327         abweichen.</para>
328
329         <note>
330          <para>
331           Vor der Umbenennung in kivitendo hieß diese Datei noch <filename>config/lx_office.conf</filename>. Aus Gründen der Kompatibilität
332           wird diese Datei eingelesen, sofern die Datei <filename>config/kivitendo.conf</filename> nicht existiert.
333          </para>
334         </note>
335
336         <para>Diese Hauptkonfigurationsdatei ist dann eine
337         installationsspezifische Datei, d.h. sie enthält bspw. lokale
338         Passwörter und wird auch nicht im Versionsmanagement (git)
339         verwaltet.</para>
340
341         <para>Die Konfiguration ist ferner serverabhängig, d.h. für alle
342         Mandaten, bzw. Datenbanken gleich.</para>
343       </sect2>
344
345       <sect2 id="config.config-file.sections-parameters">
346         <title>Abschnitte und Parameter</title>
347
348         <para>Die Konfigurationsdatei besteht aus mehreren Teilen, die
349         entsprechend kommentiert sind:</para>
350
351         <itemizedlist>
352           <listitem><para><literal>authentication</literal> (siehe Abschnitt "<xref
353           linkend="Benutzerauthentifizierung-und-Administratorpasswort"/>" in diesem Kapitel)</para></listitem>
354
355           <listitem><para><literal>authentication/database</literal></para></listitem>
356
357           <listitem><para><literal>authentication/ldap</literal></para></listitem>
358
359           <listitem><para><literal>system</literal></para></listitem>
360
361           <listitem><para><literal>paths</literal></para></listitem>
362
363           <listitem><para><literal>mail_delivery</literal> (siehe Abschnitt "<xref linkend="config.sending-email.smtp"/>)</para></listitem>
364
365           <listitem><para><literal>applications</literal></para></listitem>
366
367           <listitem><para><literal>environment</literal></para></listitem>
368
369
370           <listitem><para><literal>print_templates</literal></para></listitem>
371
372           <listitem><para><literal>task_server</literal></para></listitem>
373
374           <listitem><para><literal>periodic_invoices</literal></para></listitem>
375
376           <listitem><para><literal>self_tests</literal></para></listitem>
377
378           <listitem><para><literal>console</literal></para></listitem>
379
380           <listitem><para><literal>testing</literal></para></listitem>
381
382           <listitem><para><literal>testing/database</literal></para></listitem>
383
384           <listitem><para><literal>debug</literal></para></listitem>
385         </itemizedlist>
386
387         <para>Die üblicherweise wichtigsten Parameter, die am Anfang
388         einzustellen oder zu kontrollieren sind, sind:</para>
389
390         <programlisting>[authentication]
391 admin_password = geheim
392
393 [authentication/database]
394 host     = localhost
395 port     = 5432
396 db       = kivitendo_auth
397 user     = postgres
398 password =</programlisting>
399
400         <para>Nutzt man wiederkehrende Rechnungen, kann man unter
401         <varname>[periodic_invoices]</varname> den Login eines Benutzers
402         angeben, der nach Erstellung der Rechnungen eine entsprechende E-Mail
403         mit Informationen über die erstellten Rechnungen bekommt.</para>
404
405         <para>kivitendo bringt eine eigene Komponente zur zeitgesteuerten Ausführung bestimmter Aufgaben mit, den <link
406         linkend="config.task-server">Taskserver</link>. Er wird u.a. für Features wie die <link
407         linkend="features.periodic-invoices">wiederkehrenden Rechnungen</link> benötigt, erledigt aber auch andere erforderliche Aufgaben
408         und muss daher in Betrieb genommen werden. Der Taskserver benötigt zwei Konfigurationseinstellungen, die unter
409         <varname>[task_server]</varname> anzugeben sind: ein Mandant (entweder der Mandantenname oder eine Datenbank-ID, Variable
410         <varname>client</varname>), aus dem die Datenbankkonfiguration entnommen wird, sowie ein Login (Variable <varname>login</varname>)
411         eines Benutzers, der für gewisse Dinge wie die Rechnungserstellung als Verkäufer eingetragen wird.</para>
412
413         <para>Für Entwickler finden sich unter <varname>[debug]</varname>
414         wichtige Funktionen, um die Fehlersuche zu erleichtern.</para>
415       </sect2>
416
417       <sect2 id="config.config-file.prior-versions">
418         <title>Versionen vor 2.6.3</title>
419
420         <para>In älteren kivitendo Versionen gab es im Verzeichnis
421         <filename>config</filename> die Dateien
422         <filename>authentication.pl</filename> und
423         <filename>lx-erp.conf</filename>, die jeweils Perl-Dateien waren. Es
424         gab auch die Möglichkeit, eine lokale Version der Konfigurationsdatei
425         zu erstellen (<filename>lx-erp-local.conf</filename>). Dies ist ab
426         2.6.3 nicht mehr möglich, aber auch nicht mehr nötig.</para>
427
428         <para>Beim Update von einer kivitendo-Version vor 2.6.3 auf 2.6.3 oder
429         jünger müssen die Einstellungen aus den alten Konfigurationsdateien
430         manuell übertragen und die alten Konfigurationsdateien anschließend
431         gelöscht oder verschoben werden. Ansonsten zeigt kivitendo eine
432         entsprechende Fehlermeldung an.</para>
433       </sect2>
434     </sect1>
435
436     <sect1 id="Anpassung-der-PostgreSQL-Konfiguration">
437       <title>Anpassung der PostgreSQL-Konfiguration</title>
438
439       <para>PostgreSQL muss auf verschiedene Weisen angepasst werden.</para>
440
441       <sect2 id="Zeichensätze-die-Verwendung-von-UTF-8">
442         <title>Zeichensätze/die Verwendung von Unicode/UTF-8</title>
443
444               <para>kivitendo setzt zwingend voraus, dass die Datenbank Unicode/UTF-8 als Encoding einsetzt. Bei aktuellen Serverinstallationen
445               braucht man hier meist nicht einzugreifen.</para>
446
447         <para>Das Encoding des Datenbankservers kann überprüft werden. Ist das Encoding der Datenbank "template1" "Unicode" bzw. "UTF-8", so
448         braucht man nichts weiteres diesbezüglich unternehmen. Zum Testen:</para>
449
450         <programlisting>su postgres
451 echo '\l' | psql
452 exit </programlisting>
453
454         <para>Andernfalls ist es notwendig, einen neuen Datenbankcluster mit
455         Unicode-Encoding anzulegen und diesen zu verwenden. Unter Debian und
456         Ubuntu kann dies z.B. für PostgreSQL 9.3 mit dem folgenden Befehl
457         getan werden:</para>
458
459         <programlisting>pg_createcluster --locale=de_DE.UTF-8 --encoding=UTF-8 9.3 clustername</programlisting>
460
461         <para>Die Datenbankversionsnummer muss an die tatsächlich verwendete
462         Versionsnummer angepasst werden.</para>
463
464         <para>Unter anderen Distributionen gibt es ähnliche Methoden.</para>
465
466         <para>Das Encoding einer Datenbank kann in <command>psql</command> mit
467         <literal>\l</literal> geprüft werden.</para>
468       </sect2>
469
470       <sect2 id="Änderungen-an-Konfigurationsdateien">
471         <title>Änderungen an Konfigurationsdateien</title>
472
473         <para>In der Datei <filename>postgresql.conf</filename>, die je nach
474         Distribution in verschiedenen Verzeichnissen liegen kann (z.B.
475         <filename>/var/lib/pgsql/data/</filename> oder
476         <filename>/etc/postgresql/</filename>, muss sichergestellt werden,
477         dass TCP/IP-Verbindungen aktiviert sind. Das Verhalten wird über den
478         Parameter <varname>listen_address</varname> gesteuert. Laufen
479         PostgreSQL und kivitendo auf demselben Rechner, so kann dort der Wert
480         <literal>localhost</literal> verwendet werden. Andernfalls müssen
481         Datenbankverbindungen auch von anderen Rechnern aus zugelassen werden,
482         was mit dem Wert <literal>*</literal> geschieht.</para>
483
484         <para>In der Datei <filename>pg_hba.conf</filename>, die im gleichen
485         Verzeichnis wie die <filename>postgresql.conf</filename> zu finden
486         sein sollte, müssen die Berichtigungen für den Zugriff geändert
487         werden. Hier gibt es mehrere Möglichkeiten. Sinnvoll ist es nur die
488         nögiten Verbindungen immer zuzulassen, für eine lokal laufenden
489         Datenbank zum Beispiel:</para>
490
491         <programlisting>local all kivitendo password
492 host all kivitendo 127.0.0.1 255.255.255.255 password</programlisting>
493       </sect2>
494
495       <sect2 id="Erweiterung-für-servergespeicherte-Prozeduren">
496         <title>Erweiterung für servergespeicherte Prozeduren</title>
497
498         <para>In der Datenbank <literal>template1</literal> muss die
499         Unterstützung für servergespeicherte Prozeduren eingerichet werden.
500         Melden Sie sich dafür als Benutzer “postgres” an der Datenbank an:
501         <programlisting>su - postgres
502 psql template1</programlisting>
503
504         führen Sie die folgenden Kommandos aus:</para>
505
506         <programlisting>create language 'plpgsql';
507 \q</programlisting>
508       </sect2>
509
510       <sect2 id="Datenbankbenutzer-anlegen">
511         <title>Datenbankbenutzer anlegen</title>
512
513         <para>Wenn Sie nicht den Datenbanksuperuser “postgres” zum Zugriff
514         benutzen wollen, so sollten Sie bei PostgreSQL einen neuen Benutzer
515         anlegen. Ein Beispiel, wie Sie einen neuen Benutzer anlegen
516         können:</para>
517
518         <para>Die Frage, ob der neue User Superuser sein soll, können Sie mit nein
519         beantworten, genauso ist die Berechtigung neue User (Roles) zu
520         generieren nicht nötig.</para>
521               <programlisting>su - postgres
522 createuser -d -P kivitendo
523 exit</programlisting>
524
525         <para>Wenn Sie später einen Datenbankzugriff konfigurieren, verändern
526         Sie den evtl. voreingestellten Benutzer “postgres” auf “kivitendo” bzw.
527         den hier gewählten Benutzernamen.</para>
528       </sect2>
529     </sect1>
530
531     <sect1 id="Apache-Konfiguration">
532       <title>Webserver-Konfiguration</title>
533
534       <sect2>
535         <title>Grundkonfiguration mittels CGI</title>
536
537         <note>
538           <para>Für einen deutlichen Performanceschub sorgt die Ausführung
539           mittels FastCGI/FCGI. Die Einrichtung wird ausführlich im Abschnitt
540           <xref linkend="Apache-Konfiguration.FCGI" /> beschrieben.</para>
541         </note>
542
543         <para>Der Zugriff auf das Programmverzeichnis muss in der Apache
544         Webserverkonfigurationsdatei <literal>httpd.conf</literal> eingestellt
545         werden. Fügen Sie den folgenden Abschnitt dieser Datei oder einer
546         anderen Datei hinzu, die beim Starten des Webservers eingelesen
547         wird:</para>
548
549         <programlisting>AddHandler cgi-script .pl
550 Alias /kivitendo-erp/ /var/www/kivitendo-erp/
551
552 &lt;Directory /var/www/kivitendo-erp&gt;
553  Options ExecCGI Includes FollowSymlinks
554 &lt;/Directory&gt;
555
556 &lt;Directory /var/www/kivitendo-erp/users&gt;
557  Order Deny,Allow
558  Deny from All
559 &lt;/Directory&gt;</programlisting>
560
561         <para>Ersetzen Sie dabei die Pfade durch diejenigen, in die Sie vorher
562         das kivitendo-Archiv entpacket haben.</para>
563
564         <note>
565           <para>Vor den einzelnen Optionen muss bei einigen Distributionen ein
566           Plus ‘<literal>+</literal>’ gesetzt werden.</para>
567         </note>
568
569         <para>Auf einigen Webservern werden manchmal die Grafiken und
570         Style-Sheets nicht ausgeliefert. In solchen Fällen hat es oft
571         geholfen, die folgende Option in die Konfiguration aufzunehmen:</para>
572
573         <programlisting>EnableSendfile Off</programlisting>
574       </sect2>
575
576       <sect2 id="Apache-Konfiguration.FCGI"
577              xreflabel="Konfiguration für FastCGI/FCGI">
578         <title>Konfiguration für FastCGI/FCGI</title>
579
580         <sect3 id="Apache-Konfiguration.FCGI.WasIstEs">
581           <title>Was ist FastCGI?</title>
582
583           <para>Direkt aus <ulink
584           url="http://de.wikipedia.org/wiki/FastCGI">Wikipedia</ulink>
585           kopiert:</para>
586
587           <para><citation> FastCGI ist ein Standard für die Einbindung
588           externer Software zur Generierung dynamischer Webseiten in einem
589           Webserver. FastCGI ist vergleichbar zum Common Gateway Interface
590           (CGI), wurde jedoch entwickelt, um dessen Performance-Probleme zu
591           umgehen. </citation></para>
592         </sect3>
593
594         <sect3 id="Apache-Konfiguration.FCGI.Warum">
595           <title>Warum FastCGI?</title>
596
597           <para>Perl Programme (wie kivitendo eines ist) werden nicht statisch
598           kompiliert. Stattdessen werden die Quelldateien bei jedem Start
599           übersetzt, was bei kurzen Laufzeiten einen Großteil der Laufzeit
600           ausmacht. Während SQL Ledger einen Großteil der Funktionalität in
601           einzelne Module kapselt, um immer nur einen kleinen Teil laden zu
602           müssen, ist die Funktionalität von kivitendo soweit gewachsen, dass
603           immer mehr Module auf den Rest des Programms zugreifen. Zusätzlich
604           benutzen wir umfangreiche Bibliotheken um Funktionaltät nicht selber
605           entwickeln zu müssen, die zusätzliche Ladezeit kosten. All dies
606           führt dazu dass ein kivitendo Aufruf der Kernmasken mittlerweile
607           deutlich länger dauert als früher, und dass davon 90% für das Laden
608           der Module verwendet wird.</para>
609
610           <para>Mit FastCGI werden nun die Module einmal geladen, und danach
611           wird nur die eigentliche Programmlogik ausgeführt.</para>
612         </sect3>
613
614         <sect3 id="Apache-Konfiguration.FCGI.WebserverUndPlugin">
615           <title>Getestete Kombinationen aus Webservern und Plugin</title>
616
617           <para>Folgende Kombinationen sind getestet:</para>
618
619           <itemizedlist>
620             <listitem>
621               <para>Apache 2.2.11 (Ubuntu) und mod_fcgid.</para>
622             </listitem>
623
624             <listitem>
625               <para>Apache 2.2.11 / 2.2.22 (Ubuntu) und mod_fastcgi.</para>
626             </listitem>
627           </itemizedlist>
628
629           <para>Dabei wird mod_fcgid empfohlen, weil mod_fastcgi seit geraumer
630           Zeit nicht mehr weiter entwickelt wird. Im Folgenden wird auf
631           mod_fastcgi nicht mehr explizit eingegangen.</para>
632
633           <para>Als Perl Backend wird das Modul <filename>FCGI.pm</filename>
634           verwendet.</para>
635
636           <warning>
637             <para>FCGI-Versionen ab 0.69 und bis zu 0.71 inklusive sind extrem strict in der Behandlung von Unicode, und verweigern
638             bestimmte Eingaben von kivitendo. Falls es Probleme mit Umlauten in Ihrere Installation gibt, muss zwingend Version 0.68 oder
639             aber Version 0.72 und neuer eingesetzt werden.</para>
640
641             <para>Mit <ulink url="http://www.cpan.org">CPAN</ulink> lässt sie sich die Vorgängerversion wie folgt
642             installieren:</para>
643
644             <programlisting>force install M/MS/MSTROUT/FCGI-0.68.tar.gz</programlisting>
645           </warning>
646         </sect3>
647
648         <sect3 id="Apache-Konfiguration.FCGI.Konfiguration">
649           <title>Konfiguration des Webservers</title>
650
651           <para>Bevor Sie versuchen, eine kivitendo Installation unter FCGI
652           laufen zu lassen, empfliehlt es sich die Installation ersteinmal
653           unter CGI aufzusetzen. FCGI macht es nicht einfach Fehler zu
654           debuggen die beim ersten aufsetzen auftreten können. Sollte die
655           Installation schon funktionieren, lesen Sie weiter.</para>
656
657           <para>Zuerst muss das FastCGI-Modul aktiviert werden. Dies kann
658           unter Debian/Ubuntu z.B. mit folgendem Befehl geschehen:</para>
659
660           <programlisting>a2enmod fcgid</programlisting>
661
662           <para>Die Konfiguration für die Verwendung von kivitendo mit FastCGI
663           erfolgt durch Anpassung der vorhandenen <function>Alias</function>-
664           und <function>Directory</function>-Direktiven. Dabei wird zwischen
665           dem Installationspfad von kivitendo im Dateisystem
666           ("<filename>/path/to/kivitendo-erp</filename>") und der URL
667           unterschieden, unter der kivitendo im Webbrowser erreichbar ist
668           ("<filename>/url/for/kivitendo-erp</filename>").</para>
669
670           <para>Folgender Konfigurationsschnipsel funktioniert mit
671           mod_fastcgi:</para>
672
673           <programlisting>AliasMatch ^/url/for/kivitendo-erp/[^/]+\.pl /path/to/kivitendo-erp/dispatcher.fcgi
674 Alias       /url/for/kivitendo-erp/          /path/to/kivitendo-erp/
675
676 &lt;Directory /path/to/kivitendo-erp&gt;
677   AllowOverride All
678   Options ExecCGI Includes FollowSymlinks
679   Order Allow,Deny
680   Allow from All
681 &lt;/Directory&gt;
682
683 &lt;DirectoryMatch /path/to/kivitendo-erp/users&gt;
684   Order Deny,Allow
685   Deny from All
686 &lt;/DirectoryMatch&gt;</programlisting>
687
688           <para>Seit mod_fcgid-Version 2.3.6 gelten sehr kleine Grenzen für
689           die maximale Größe eines Requests. Diese sollte wie folgt
690           hochgesetzt werden:</para>
691
692           <programlisting>FcgidMaxRequestLen 10485760</programlisting>
693
694           <para>Das ganze sollte dann so aussehen:</para>
695
696           <programlisting>AddHandler fcgid-script .fpl
697 AliasMatch ^/url/for/kivitendo-erp/[^/]+\.pl /path/to/kivitendo-erp/dispatcher.fpl
698 Alias       /url/for/kivitendo-erp/          /path/to/kivitendo-erp/
699 FcgidMaxRequestLen 10485760
700
701 &lt;Directory /path/to/kivitendo-erp&gt;
702   AllowOverride All
703   Options ExecCGI Includes FollowSymlinks
704   Order Allow,Deny
705   Allow from All
706 &lt;/Directory&gt;
707
708 &lt;DirectoryMatch /path/to/kivitendo-erp/users&gt;
709   Order Deny,Allow
710   Deny from All
711 &lt;/DirectoryMatch&gt;</programlisting>
712
713           <para>Hierdurch wird nur ein zentraler Dispatcher gestartet. Alle
714           Zugriffe auf die einzelnen Scripte werden auf diesen umgeleitet.
715           Dadurch, dass zur Laufzeit öfter mal Scripte neu geladen werden,
716           gibt es hier kleine Performance-Einbußen.</para>
717
718           <para>Es ist möglich, die gleiche kivitendo Version parallel unter
719           CGI und FastCGI zu betreiben. Dafür bleiben die Directorydirektiven
720           wie oben beschrieben, die URLs werden aber umgeleitet:</para>
721
722           <programlisting># Zugriff über CGI
723 Alias       /url/for/kivitendo-erp                /path/to/kivitendo-erp
724
725 # Zugriff mit mod_fcgid:
726 AliasMatch ^/url/for/kivitendo-erp-fcgid/[^/]+\.pl /path/to/kivitendo-erp/dispatcher.fpl
727 Alias       /url/for/kivitendo-erp-fcgid/          /path/to/kivitendo-erp/</programlisting>
728
729           <para>Dann ist unter <filename>/url/for/kivitendo-erp/</filename>
730           die normale Version erreichbar, und unter
731           <constant>/url/for/kivitendo-erp-fcgid/</constant> die
732           FastCGI-Version.</para>
733         </sect3>
734       </sect2>
735     </sect1>
736
737     <sect1 id="config.task-server">
738       <title>Der Task-Server</title>
739
740       <para>Der Task-Server ist ein Prozess, der im Hintergrund läuft, in regelmäßigen Abständen nach abzuarbeitenden Aufgaben sucht und
741       diese zu festgelegten Zeitpunkten abarbeitet (ähnlich wie Cron). Dieser Prozess wird u.a. für die Erzeugung der wiederkehrenden
742       Rechnungen und weitere essenzielle Aufgaben benutzt.</para>
743
744       <sect2 id="Konfiguration-des-Task-Servers">
745         <title>Verfügbare und notwendige Konfigurationsoptionen</title>
746
747         <para>Die Konfiguration erfolgt über den Abschnitt
748         <literal>[task_server]</literal> in der Datei
749         <filename>config/kivitendo.conf</filename>. Die dort verfügbaren
750         Optionen sind:</para>
751
752         <variablelist>
753           <varlistentry>
754             <term><varname>client</varname></term>
755
756             <listitem>
757               <para>Name oder Datenbank-ID eines vorhandenen kivitendo-Mandanten, der benutzt wird, um die zu verwendende
758               Datenbankverbindung auszulesen. Der Mandant muss in der Administration angelegt werden. Diese Option muss angegeben
759               werden.</para>
760
761               <para>Diese Option kam mit Release v3.x.0 hinzu und muss daher in Konfigurationen, die von älteren Versionen aktualisiert
762               wurden, ergänzt werden.</para>
763             </listitem>
764           </varlistentry>
765
766           <varlistentry>
767             <term><varname>login</varname></term>
768
769             <listitem>
770               <para>gültiger kivitendo-Benutzername, der z.B. als Verkäufer beim Erzeugen wiederkehrender Rechnungen benötigt wird. Der
771               Benutzer muss in der Administration angelegt werden. Diese Option muss angegeben werden.</para>
772             </listitem>
773           </varlistentry>
774
775           <varlistentry>
776             <term><varname>run_as</varname></term>
777
778             <listitem>
779               <para>Wird der Server vom Systembenutzer <literal>root</literal>
780               gestartet, so wechselt er auf den mit <literal>run_as</literal>
781               angegebenen Systembenutzer. Der Systembenutzer muss dieselben
782               Lese- und Schreibrechte haben, wie auch der Webserverbenutzer
783               (siehe see <xref
784               linkend="Manuelle-Installation-des-Programmpaketes" />). Daher
785               ist es sinnvoll, hier denselben Systembenutzer einzutragen,
786               unter dem auch der Webserver läuft.</para>
787             </listitem>
788           </varlistentry>
789
790           <varlistentry>
791             <term><varname>debug</varname></term>
792
793             <listitem>
794               <para>Schaltet Debug-Informationen an und aus.</para>
795             </listitem>
796           </varlistentry>
797         </variablelist>
798       </sect2>
799
800       <sect2 id="Einbinden-in-den-Boot-Prozess">
801         <title>Automatisches Starten des Task-Servers beim Booten</title>
802
803         <para>Der Task-Server verhält sich von seinen Optionen her wie ein
804         reguläres SystemV-kompatibles Boot-Script. Außerdem wechselt er beim
805         Starten automatisch in das kivitendo-Installationsverzeichnis.</para>
806
807         <para>Deshalb ist es möglich, ihn durch Setzen eines symbolischen
808         Links aus einem der Runlevel-Verzeichnisse heraus in den Boot-Prozess
809         einzubinden. Da das bei neueren Linux-Distributionen aber nicht
810         zwangsläufig funktioniert, werden auch Start-Scripte mitgeliefert, die
811         anstelle eines symbolischen Links verwendet werden können.</para>
812
813         <sect3>
814           <title>SystemV-basierende Systeme (z.B. Debian, ältere OpenSUSE, ältere Fedora Core)</title>
815
816           <para>Kopieren Sie die Datei
817           <filename>scripts/boot/system-v/kivitendo-server</filename>
818           nach <filename>/etc/init.d/kivitendo-server</filename>. Passen
819           Sie in der kopierten Datei den Pfad zum Task-Server an (Zeile
820           <literal>DAEMON=....</literal>). Binden Sie das Script in den
821           Boot-Prozess ein. Dies ist distributionsabhängig:</para>
822
823           <itemizedlist>
824             <listitem>
825               <para>Debian-basierende Systeme:</para>
826
827               <programlisting>update-rc.d kivitendo-task-server defaults
828 # Nur bei Debian Squeeze und neuer:
829 insserv kivitendo-task-server</programlisting>
830             </listitem>
831
832             <listitem>
833               <para>Ältere OpenSUSE und ältere Fedora Core:</para>
834
835               <programlisting>chkconfig --add kivitendo-task-server</programlisting>
836             </listitem>
837           </itemizedlist>
838
839           <para>Danach kann der Task-Server mit dem folgenden Befehl gestartet
840           werden:</para>
841
842           <programlisting>/etc/init.d/kivitendo-task-server start</programlisting>
843         </sect3>
844
845         <sect3>
846           <title>Upstart-basierende Systeme (z.B. Ubuntu)</title>
847
848           <para>Kopieren Sie die Datei
849           <filename>scripts/boot/upstart/kivitendo-task-server.conf</filename>
850           nach <filename>/etc/init/kivitendo-task-server.conf</filename>.
851           Passen Sie in der kopierten Datei den Pfad zum Task-Server an (Zeile
852           <literal>exec ....</literal>).</para>
853
854           <para>Danach kann der Task-Server mit dem folgenden Befehl gestartet
855           werden:</para>
856
857           <programlisting>service kivitendo-task-server start</programlisting>
858         </sect3>
859
860         <sect3>
861           <title>systemd-basierende Systeme (z.B. neure OpenSUSE, neuere Fedora Core)</title>
862
863           <para>Verlinken Sie die Datei <filename>scripts/boot/systemd/kivitendo-task-server.service</filename> nach
864           <filename>/etc/systemd/system/</filename>. Passen Sie in der kopierten Datei den Pfad zum Task-Server an (Zeile
865           <literal>ExecStart=....</literal> und <literal>ExecStop=...</literal>). Binden Sie das Script in den Boot-Prozess ein.
866           </para>
867
868           <para>Alle hierzu benötigten Befehle sehen so aus:</para>
869
870           <programlisting>cd /var/www/kivitendo-erp/scripts/boot/systemd
871 ln -s $(pwd)/kivitendo-task-server.service /etc/systemd/system/</programlisting>
872
873           <para>Danach kann der Task-Server mit dem folgenden Befehl gestartet
874           werden:</para>
875
876           <programlisting>systemctl start kivitendo-task-server.service</programlisting>
877         </sect3>
878       </sect2>
879
880       <sect2 id="Prozesskontrolle">
881         <title>Wie der Task-Server gestartet und beendet wird</title>
882
883         <para>Der Task-Server wird wie folgt kontrolliert:</para>
884
885         <programlisting>./scripts/task_server.pl Befehl</programlisting>
886
887         <para><literal>Befehl</literal> ist dabei eine der folgenden
888         Optionen:</para>
889
890         <itemizedlist>
891           <listitem>
892             <para><literal>start</literal> startet eine neue Instanz des
893             Task-Servers. Die Prozess-ID wird innerhalb des
894             <filename>users</filename>-Verzeichnisses abgelegt.</para>
895           </listitem>
896
897           <listitem>
898             <para><literal>stop</literal> beendet einen laufenden
899             Task-Server.</para>
900           </listitem>
901
902           <listitem>
903             <para><literal>restart</literal> beendet und startet ihn
904             neu.</para>
905           </listitem>
906
907           <listitem>
908             <para><literal>status</literal> berichtet, ob der Task-Server
909             läuft.</para>
910           </listitem>
911         </itemizedlist>
912
913         <para>Der Task-Server wechselt beim Starten automatisch in das
914         kivitendo-Installationsverzeichnis.</para>
915
916         <para>Dieselben Optionen können auch für die SystemV-basierenden
917         Runlevel-Scripte benutzt werden (siehe oben).</para>
918       </sect2>
919       <sect2 id="Prozesskontrolle2">
920         <title>Task-Server mit mehreren Mandanten</title>
921
922         <para>Beim Task-Server werden der zu verwendende Mandant und Login-Name des Benutzers, unter dem der Task-Server laufen soll, in die
923         Konfigurationsdatei geschrieben. Hat man mehrere Mandanten, muss man auch mehrere Konfigurationsdateien anlegen.</para>
924
925         <para>Die Konfigurationsdatei ist eine Kopie der Datei kivitendo.conf, wo in der Kategorie <varname>[task_server]</varname> die
926         gewünschten Werte für <varname>client</varname> und <varname>login</varname> eingetragen werden.</para>
927
928         <para>Der alternative Task-Server wird dann mit folgendem Befehl
929         gestartet:</para>
930
931         <programlisting>./scripts/task_server.pl -c config/DATEINAME.conf</programlisting>
932       </sect2>
933     </sect1>
934
935     <sect1 id="Benutzerauthentifizierung-und-Administratorpasswort">
936       <title>Benutzerauthentifizierung und Administratorpasswort</title>
937
938       <para>Informationen über die Einrichtung der Benutzerauthentifizierung,
939       über die Verwaltung von Gruppen und weitere Einstellungen</para>
940
941       <sect2 id="Grundlagen-zur-Benutzerauthentifizierung">
942         <title>Grundlagen zur Benutzerauthentifizierung</title>
943
944         <para>kivitendo verwaltet die Benutzerinformationen in einer
945         Datenbank, die im folgenden “Authentifizierungsdatenbank” genannt
946         wird. Für jeden Benutzer kann dort eine eigene Datenbank für die
947         eigentlichen Finanzdaten hinterlegt sein. Diese beiden Datenbanken
948         können, müssen aber nicht unterschiedlich sein.</para>
949
950         <para>Im einfachsten Fall gibt es für kivitendo nur eine einzige
951         Datenbank, in der sowohl die Benutzerinformationen als auch die Daten
952         abgelegt werden.</para>
953
954         <para>Zusätzlich ermöglicht es kivitendo, dass die Benutzerpasswörter
955         entweder gegen die Authentifizierungsdatenbank oder gegen einen
956         LDAP-Server überprüft werden.</para>
957
958         <para>Welche Art der Passwortüberprüfung kivitendo benutzt und wie
959         kivitendo die Authentifizierungsdatenbank erreichen kann, wird in der
960         Konfigurationsdatei <filename>config/kivitendo.conf</filename>
961         festgelegt. Diese muss bei der Installation und bei einem Upgrade von
962         einer Version vor v2.6.0 angelegt werden. Eine
963         Beispielkonfigurationsdatei
964         <filename>config/kivitendo.conf.default</filename> existiert, die als
965         Vorlage benutzt werden kann.</para>
966       </sect2>
967
968       <sect2 id="Administratorpasswort">
969         <title>Administratorpasswort</title>
970
971         <para>Das Passwort, das zum Zugriff auf das Aministrationsinterface
972         benutzt wird, wird ebenfalls in dieser Datei gespeichert. Es kann auch
973         nur dort und nicht mehr im Administrationsinterface selber geändert
974         werden. Der Parameter dazu heißt <varname>admin_password</varname> im
975         Abschnitt <varname>[authentication]</varname>.</para>
976       </sect2>
977
978       <sect2 id="Authentifizierungsdatenbank">
979         <title>Authentifizierungsdatenbank</title>
980
981         <para>Die Verbindung zur Authentifizierungsdatenbank wird mit den
982         Parametern in <varname>[authentication/database]</varname>
983         konfiguriert. Hier sind die folgenden Parameter anzugeben:</para>
984
985         <variablelist>
986           <varlistentry>
987             <term><literal>host</literal></term>
988
989             <listitem>
990               <para>Der Rechnername oder die IP-Adresse des
991               Datenbankservers</para>
992             </listitem>
993           </varlistentry>
994
995           <varlistentry>
996             <term><literal>port</literal></term>
997
998             <listitem>
999               <para>Die Portnummer des Datenbankservers, meist 5432</para>
1000             </listitem>
1001           </varlistentry>
1002
1003           <varlistentry>
1004             <term><literal>db</literal></term>
1005
1006             <listitem>
1007               <para>Der Name der Authentifizierungsdatenbank</para>
1008             </listitem>
1009           </varlistentry>
1010
1011           <varlistentry>
1012             <term><literal>user</literal></term>
1013
1014             <listitem>
1015               <para>Der Benutzername, mit dem sich kivitendo beim
1016               Datenbankserver anmeldet (z.B.
1017               "<literal>postgres</literal>")</para>
1018             </listitem>
1019           </varlistentry>
1020
1021           <varlistentry>
1022             <term><literal>password</literal></term>
1023
1024             <listitem>
1025               <para>Das Passwort für den Datenbankbenutzer</para>
1026             </listitem>
1027           </varlistentry>
1028         </variablelist>
1029
1030         <para>Die Datenbank muss noch nicht existieren. kivitendo kann sie
1031         automatisch anlegen (mehr dazu siehe unten).</para>
1032       </sect2>
1033
1034       <sect2 id="Passwortüberprüfung">
1035         <title>Passwortüberprüfung</title>
1036
1037         <para>kivitendo unterstützt Passwortüberprüfung auf zwei Arten: gegen
1038         die Authentifizierungsdatenbank und gegen einen externen LDAP- oder
1039         Active-Directory-Server. Welche davon benutzt wird, regelt der
1040         Parameter <varname>module</varname> im Abschnitt
1041         <varname>[authentication]</varname>.</para>
1042
1043         <para>Sollen die Benutzerpasswörter in der Authentifizierungsdatenbank
1044         gespeichert werden, so muss der Parameter <varname>module</varname>
1045         den Wert <literal>DB</literal> enthalten. In diesem Fall können sowohl
1046         der Administrator als auch die Benutzer selber ihre Psaswörter in
1047         kivitendo ändern.</para>
1048
1049         <para>Soll hingegen ein externer LDAP- oder Active-Directory-Server
1050         benutzt werden, so muss der Parameter <varname>module</varname> auf
1051         <literal>LDAP</literal> gesetzt werden. In diesem Fall müssen
1052         zusätzliche Informationen über den LDAP-Server im Abschnitt
1053         <literal>[authentication/ldap]</literal> angegeben werden:</para>
1054
1055         <variablelist>
1056           <varlistentry>
1057             <term><literal>host</literal></term>
1058
1059             <listitem>
1060               <para>Der Rechnername oder die IP-Adresse des LDAP- oder
1061               Active-Directory-Servers. Diese Angabe ist zwingend
1062               erforderlich.</para>
1063             </listitem>
1064           </varlistentry>
1065
1066           <varlistentry>
1067             <term><literal>port</literal></term>
1068
1069             <listitem>
1070               <para>Die Portnummer des LDAP-Servers; meist 389.</para>
1071             </listitem>
1072           </varlistentry>
1073
1074           <varlistentry>
1075             <term><literal>tls</literal></term>
1076
1077             <listitem>
1078               <para>Wenn Verbindungsverschlüsselung gewünscht ist, so diesen
1079               Wert auf ‘<literal>1</literal>’ setzen, andernfalls auf
1080               ‘<literal>0</literal>’ belassen</para>
1081             </listitem>
1082           </varlistentry>
1083
1084           <varlistentry>
1085             <term><literal>attribute</literal></term>
1086
1087             <listitem>
1088               <para>Das LDAP-Attribut, in dem der Benutzername steht, den der
1089               Benutzer eingegeben hat. Für Active-Directory-Server ist dies
1090               meist ‘<literal>sAMAccountName</literal>’, für andere
1091               LDAP-Server hingegen ‘<literal>uid</literal>’. Diese Angabe ist
1092               zwingend erforderlich.</para>
1093             </listitem>
1094           </varlistentry>
1095
1096           <varlistentry>
1097             <term><literal>base_dn</literal></term>
1098
1099             <listitem>
1100               <para>Der Abschnitt des LDAP-Baumes, der durchsucht werden soll.
1101               Diese Angabe ist zwingend erforderlich.</para>
1102             </listitem>
1103           </varlistentry>
1104
1105           <varlistentry>
1106             <term><literal>filter</literal></term>
1107
1108             <listitem>
1109               <para>Ein optionaler LDAP-Filter. Enthält dieser Filter das Wort
1110               <literal>&lt;%login%&gt;</literal>, so wird dieses durch den vom
1111               Benutzer eingegebenen Benutzernamen ersetzt. Andernfalls wird
1112               der LDAP-Baum nach einem Element durchsucht, bei dem das oben
1113               angegebene Attribut mit dem Benutzernamen identisch ist.</para>
1114             </listitem>
1115           </varlistentry>
1116
1117           <varlistentry>
1118             <term><literal>bind_dn</literal> und
1119             <literal>bind_password</literal></term>
1120
1121             <listitem>
1122               <para>Wenn der LDAP-Server eine Anmeldung erfordert, bevor er
1123               durchsucht werden kann (z.B. ist dies bei
1124               Active-Directory-Servern der Fall), so kann diese hier angegeben
1125               werden. Für Active-Directory-Server kann als
1126               ‘<literal>bind_dn</literal>’ entweder eine komplette LDAP-DN wie
1127               z.B. ‘<literal>cn=Martin
1128               Mustermann,cn=Users,dc=firmendomain</literal>’ auch nur der
1129               volle Name des Benutzers eingegeben werden; in diesem Beispiel
1130               also ‘<literal>Martin Mustermann</literal>’.</para>
1131             </listitem>
1132           </varlistentry>
1133         </variablelist>
1134       </sect2>
1135
1136       <sect2 id="Name-des-Session-Cookies">
1137         <title>Name des Session-Cookies</title>
1138
1139         <para>Sollen auf einem Server mehrere kivitendo-Installationen
1140         aufgesetzt werden, so müssen die Namen der Session-Cookies für alle
1141         Installationen unterschiedlich sein. Der Name des Cookies wird mit dem
1142         Parameter <varname>cookie_name</varname> im Abschnitt
1143         <varname>[authentication]</varname>gesetzt.</para>
1144
1145         <para>Diese Angabe ist optional, wenn nur eine Installation auf dem
1146         Server existiert.</para>
1147       </sect2>
1148
1149       <sect2 id="Anlegen-der-Authentifizierungsdatenbank">
1150         <title>Anlegen der Authentifizierungsdatenbank</title>
1151
1152         <para>Nachdem alle Einstellungen in
1153         <filename>config/kivitendo.conf</filename> vorgenommen wurden, muss
1154         kivitendo die Authentifizierungsdatenbank anlegen. Dieses geschieht
1155         automatisch, wenn Sie sich im Administrationsmodul anmelden, das unter
1156         der folgenden URL erreichbar sein sollte:</para>
1157
1158         <para><ulink
1159         url="http://localhost/kivitendo-erp/controller.pl?action=Admin/login">http://localhost/kivitendo-erp/controller.pl?action=Admin/login</ulink></para>
1160       </sect2>
1161     </sect1>
1162
1163     <sect1 id="Benutzer--und-Gruppenverwaltung">
1164       <title>Mandanten-, Benutzer- und Gruppenverwaltung</title>
1165
1166       <para>Nach der Installation müssen Mandanten, Benutzer, Gruppen und Datenbanken angelegt werden. Dieses geschieht im
1167       Administrationsmenü, das Sie unter folgender URL finden:</para>
1168
1169       <para><ulink
1170       url="http://localhost/kivitendo-erp/controller.pl?action=Admin/login">http://localhost/kivitendo-erp/controller.pl?action=Admin/login</ulink></para>
1171
1172       <para>Verwenden Sie zur Anmeldung das Password, dass Sie in der Datei
1173       <filename>config/kivitendo.conf</filename> eingetragen haben.</para>
1174
1175       <sect2 id="Zusammenhänge">
1176         <title>Zusammenhänge</title>
1177
1178         <para>kivitendo verwaltet zwei Sets von Daten, die je nach Einrichtung in einer oder zwei Datenbanken gespeichert werden.</para>
1179
1180         <para>Das erste Set besteht aus Anmeldeinformationen: welche Benutzer und Mandanten gibt es, welche Gruppen, welche BenutzerIn hat
1181         Zugriff auf welche Mandanten, und welche Gruppe verfügt über welche Rechte. Diese Informationen werden in der
1182         Authentifizierungsdatenbank gespeichert. Dies ist diejenige Datenbank, deren Verbindungsparameter in der Konfigurationsdatei
1183         <filename>config/kivitendo.conf</filename> gespeichert werden.</para>
1184
1185         <para>Das zweite Set besteht aus den eigentlichen Verkehrsdaten eines Mandanten, wie beispielsweise die Stammdaten (Kunden, Lieferanten, Waren) und Belege
1186         (Angebote, Lieferscheine, Rechnungen). Diese werden in einer Mandantendatenbank gespeichert. Die
1187         Verbindungsinformationen einer solchen Mandantendatenbank werden im Administrationsbereich konfiguriert, indem man einen Mandanten
1188         anlegt und dort die Parameter einträgt. Dabei hat jeder Mandant eine eigene Datenbank.</para>
1189
1190         <para>Aufgrund des Datenbankdesigns ist es für einfache Fälle möglich, die Authentifizierungsdatenbank und eine der
1191         Mandantendatenbanken in ein und derselben Datenbank zu speichern. Arbeitet man hingegen mit mehr als einem Mandanten, wird
1192         empfohlen, für die Authentifizierungsdatenbank eine eigene Datenbank zu verwenden, die nicht gleichzeitig für einen Mandanten
1193         verwendet wird.</para>
1194      </sect2>
1195
1196       <sect2 id="Mandanten-Benutzer-Gruppen">
1197         <title>Mandanten, Benutzer und Gruppen</title>
1198
1199         <para>kivitendos Administration kennt Mandanten, Benutzer und Gruppen, die sich frei zueinander zuordnen lassen.</para>
1200
1201         <para>kivitendo kann mehrere Mandaten aus einer Installation heraus verwalten. Welcher Mandant benutzt wird, kann direkt beim Login
1202         ausgewählt werden. Für jeden Mandanten wird ein eindeutiger Name vergeben, der beim Login angezeigt wird. Weiterhin benötigt der
1203         Mandant Datenbankverbindungsparameter für seine Mandantendatenbank. Diese sollte über die <link
1204         linkend="Datenbanken-anlegen">Datenbankverwaltung</link> geschehen.</para>
1205
1206         <para>Ein Benutzer ist eine Person, die Zugriff auf kivitendo erhalten soll. Sie erhält einen Loginnamen sowie ein
1207         Passwort. Weiterhin legt der Administrator fest, an welchen Mandanten sich ein Benutzer anmelden kann, was beim Login verifiziert
1208         wird.</para>
1209
1210         <para>Gruppen dienen dazu, Benutzern innerhalb eines Mandanten Zugriff auf bestimmte Funktionen zu geben. Einer Gruppe werden dafür
1211         vom Administrator gewisse Rechte zugeordnet. Weiterhin legt der Administrator fest, für welche Mandanten eine Gruppe gilt, und
1212         welche Benutzer Mitglieder in dieser Gruppe sind. Meldet sich ein Benutzer dann an einem Mandanten an, so erhält er alle Rechte von
1213         allen denjenigen Gruppen, die zum Einen dem Mandanten zugeordnet sind und in denen der Benutzer zum Anderen Mitglied ist, </para>
1214
1215         <para>Die Reihenfolge, in der Datenbanken, Mandanten, Gruppen und Benutzer angelegt werden, kann im Prinzip beliebig gewählt
1216         werden. Die folgende Reihenfolge beinhaltet die wenigsten Arbeitsschritte:</para>
1217
1218         <orderedlist numeration="arabic">
1219           <listitem>
1220             <para>Datenbank anlegen</para>
1221           </listitem>
1222
1223           <listitem>
1224             <para>Gruppen anlegen</para>
1225           </listitem>
1226
1227           <listitem>
1228             <para>Benutzer anlegen und Gruppen als Mitglied zuordnen</para>
1229           </listitem>
1230
1231           <listitem>
1232             <para>Mandanten anlegen und Gruppen sowie Benutzer zuweisen</para>
1233           </listitem>
1234         </orderedlist>
1235       </sect2>
1236
1237       <sect2 id="Datenbanken-anlegen">
1238         <title>Datenbanken anlegen</title>
1239
1240         <para>Zuerst muss eine Datenbank angelegt werden. Verwenden Sie für
1241         den Datenbankzugriff den vorhin angelegten Benutzer (in unseren
1242         Beispielen ist dies ‘<literal>kivitendo</literal>’).</para>
1243       </sect2>
1244
1245       <sect2 id="Gruppen-anlegen">
1246         <title>Gruppen anlegen</title>
1247
1248         <para>Eine Gruppe wird in der Gruppenverwaltung angelegt. Ihr muss ein
1249         Name gegeben werden, eine Beschreibung ist hingegen optional. Nach dem
1250         Anlegen können Sie die verschiedenen Bereiche wählen, auf die
1251         Mitglieder dieser Gruppe Zugriff haben sollen.</para>
1252
1253         <para>Benutzergruppen werden zwar in der Authentifizierungsdatenbank gespeichert, gelten aber nicht automatisch für alle
1254         Mandanten. Der Administrator legt vielmehr fest, für welche Mandanten eine Gruppe gültig ist. Dies kann entweder beim Bearbeiten der
1255         Gruppe geschehen ("diese Gruppe ist gültig für Mandanten X, Y und Z"), oder aber wenn man einen Mandanten bearbeitet ("für diesen
1256         Mandanten sind die Gruppen A, B und C gültig").</para>
1257
1258         <para>Wurden bereits Benutzer angelegt, so können hier die Mitglieder dieser Gruppe festgelegt werden ("in dieser Gruppe sind die
1259         Benutzer X, Y und Z Mitglieder"). Dies kann auch nachträglich beim Bearbeiten eines Benutzers geschehen ("dieser Benutzer ist
1260         Mitglied in den Gruppen A, B und C").</para>
1261       </sect2>
1262
1263       <sect2 id="Benutzer-anlegen">
1264         <title>Benutzer anlegen</title>
1265
1266         <para>Beim Anlegen von Benutzern werden für viele Parameter Standardeinstellungen vorgenommen, die den Gepflogenheiten des deutschen
1267         Raumes entsprechen.</para>
1268
1269         <para>Zwingend anzugeben ist der Loginname. Wenn die Passwortauthentifizierung über die Datenbank eingestellt ist, so kann hier auch
1270         das Benutzerpasswort gesetzt bzw. geändert werden. Ist hingegen die LDAP-Authentifizierung aktiv, so ist das Passwort-Feld
1271         deaktiviert.</para>
1272
1273         <para>Hat man bereits Mandanten und Gruppen angelegt, so kann hier auch konfiguriert werden, auf welche Mandanten der Benutzer
1274         Zugriff hat bzw. in welchen Gruppen er Mitglied ist. Beide Zuweisungen können sowohl beim Benutzer vorgenommen werden ("dieser
1275         Benutzer hat Zugriff auf Mandanten X, Y, Z" bzw. "dieser Benutzer ist Mitglied in Gruppen X, Y und Z") als auch beim Mandanten ("auf
1276         diesen Mandanten haben Benutzer A, B und C Zugriff") bzw. bei der Gruppe ("in dieser Gruppe sind Benutzer A, B und C
1277         Mitglieder").</para>
1278       </sect2>
1279
1280       <sect2 id="Mandanten-anlegen">
1281         <title>Mandanten anlegen</title>
1282
1283         <para>Ein Mandant besteht aus Administrationssicht primär aus einem eindeutigen Namen. Weiterhin wird hier hinterlegt, welche
1284         Datenbank als Mandantendatenbank benutzt wird. Hier müssen die Zugriffsdaten einer der eben angelegten Datenbanken eingetragen
1285         werden.</para>
1286
1287         <para>Hat man bereits Benutzer und Gruppen angelegt, so kann hier auch konfiguriert werden, welche Benutzer Zugriff auf den
1288         Mandanten haben bzw. welche Gruppen für den Mandanten gültig sind. Beide Zuweisungen können sowohl beim Mandanten vorgenommen werden
1289         ("auf diesen Mandanten haben Benutzer X, Y und Z Zugriff" bzw. "für diesen Mandanten sind die Gruppen X, Y und Z gültig") als auch
1290         beim Benutzer ("dieser Benutzer hat Zugriff auf Mandanten A, B und C") bzw. bei der Gruppe ("diese Gruppe ist für Mandanten A, B und
1291         C gültig").</para>
1292       </sect2>
1293     </sect1>
1294     <sect1 id="Drucker--Systemverwaltung">
1295       <title>Drucker- und Systemverwaltung</title>
1296       <para>Im Administrationsmenü gibt es ferner noch die beiden Menüpunkte Druckeradministration und System.</para>
1297       <sect2 id="Druckeradministration">
1298         <title>Druckeradministration</title>
1299       <para>Unter dem Menüpunkt Druckeradministration lassen sich beliebig viele "Druckbefehle" im System verwalten. Diese Befehle werden mandantenweise
1300       zugeordnet. Unter Druckerbeschreibung wird der Namen des Druckbefehls festgelegt, der dann in der Druckerauswahl des Belegs angezeigt wird.</para>
1301       <para>Unter Druckbefehl definiert man den eigentlichen Druckbefehl, der direkt auf dem Webserver ausgeführt wird, bspw. 'lpr -P meinDrucker' oder ein
1302       kompletter Pfad zu einem Skript (/usr/local/src/kivitendo/scripts/pdf_druck_in_verzeichnis.sh).
1303       Wird ferner noch ein optionales Vorlagenkürzel verwendet, wird dieses Kürzel bei der Auswahl der Druckvorlagendatei mit einem Unterstrich ergänzt, ist
1304       bspw. das Kürzel 'epson_drucker' definiert, so wird beim Ausdruck eines Angebots folgende Vorlage geparst: sales_quotation_epson_drucker.tex.</para>
1305      </sect2>
1306       <sect2 id="System">
1307         <title>System sperren / entsperren</title>
1308
1309         <para>Unter dem Menüpunkt System gibt es den Eintrag 'Installation sperren/entsperren'. Setz man diese Sperre so ist der Zugang zu der gesamten kivitendo Installation gesperrt.</para>
1310         <para>Falls die Sperre gesetzt ist, erscheint anstelle der Anmeldemaske die Information: 'kivitendo ist momentan zwecks Wartungsarbeiten nicht zugänglich.'.
1311         </para>
1312         <para>Wichtig zu erwähnen ist hierbei noch, dass sich kivitendo automatisch 'sperrt', falls es bei einem Versionsupdate zu einem Datenbankfehler kam. Somit kann hier nicht aus Versehen
1313         mit einem inkonsistenten Datenbestand weitergearbeitet werden.</para>
1314      </sect2>
1315     </sect1>
1316
1317     <sect1 id="config.sending-email" xreflabel="E-Mail-Versand aus kivitendo heraus">
1318       <title>E-Mail-Versand aus kivitendo heraus</title>
1319
1320       <para>kivitendo kann direkt aus dem Programm heraus E-Mails versenden, z.B. um ein Angebot direkt an einen Kunden zu
1321       verschicken. Damit dies funktioniert, muss eingestellt werden, über welchen Server die E-Mails verschickt werden sollen. kivitendo
1322       unterstützt dabei zwei Mechanismen: Versand über einen lokalen E-Mail-Server (z.B. mit <productname>Postfix</productname> oder
1323       <productname>Exim</productname>, was auch die standardmäßig aktive Methode ist) sowie Versand über einen SMTP-Server (z.B. der des
1324       eigenen Internet-Providers).</para>
1325
1326       <para>Welche Methode und welcher Server verwendet werden, wird über die Konfigurationsdatei <filename>config/kivitendo.conf</filename>
1327       festgelegt. Dort befinden sich alle Einstellungen zu diesem Thema im Abschnitt '<literal>[mail_delivery]</literal>'.</para>
1328
1329       <sect2 id="config.sending-email.sendmail" xreflabel="E-Mail-Versand über lokalen E-Mail-Server">
1330         <title>Versand über lokalen E-Mail-Server</title>
1331
1332         <para>Diese Methode bietet sich an, wenn auf dem Server, auf dem kivitendo läuft, bereits ein funktionsfähiger E-Mail-Server wie
1333         z.B. <productname>Postfix</productname>, <productname>Exim</productname> oder <productname>Sendmail</productname> läuft.</para>
1334
1335         <para>Um diese Methode auszuwählen, muss der Konfigurationsparameter '<literal>method = sendmail</literal>' gesetzt sein. Dies ist
1336         gleichzeitig der Standardwert, falls er nicht verändert wird.</para>
1337
1338         <para>Um zu kontrollieren, wie das Programm zum Einliefern gestartet wird, dient der Parameter '<literal>sendmail =
1339         ...</literal>'. Der Standardwert verweist auf das Programm <filename>/usr/bin/sendmail</filename>, das bei allen oben genannten
1340         E-Mail-Serverprodukten für diesen Zweck funktionieren sollte.</para>
1341
1342         <para>Die Konfiguration des E-Mail-Servers selber würde den Rahmen dieses sprengen. Hierfür sei auf die Dokumentation des
1343         E-Mail-Servers verwiesen.</para>
1344       </sect2>
1345
1346       <sect2 id="config.sending-email.smtp" xreflabel="E-Mail-Versand über einen SMTP-Server">
1347         <title>Versand über einen SMTP-Server</title>
1348
1349         <para>Diese Methode bietet sich an, wenn kein lokaler E-Mail-Server vorhanden oder zwar einer vorhanden, dieser aber nicht
1350         konfiguriert ist.</para>
1351
1352         <para>Um diese Methode auszuwählen, muss der Konfigurationsparameter '<literal>method = smtp</literal>' gesetzt sein. Die folgenden
1353         Parameter dienen dabei der weiteren Konfiguration:</para>
1354
1355         <variablelist>
1356           <varlistentry>
1357             <term><varname>hostname</varname></term>
1358
1359             <listitem><para>Name oder IP-Adresse des SMTP-Servers. Standardwert: '<literal>localhost</literal>'</para></listitem>
1360           </varlistentry>
1361
1362           <varlistentry>
1363             <term><varname>port</varname></term>
1364
1365             <listitem><para>Portnummer. Der Standardwert hängt von der verwendeten Verschlüsselungsmethode ab. Gilt '<literal>security =
1366             none</literal>' oder '<literal>security = tls</literal>', so ist 25 die Standardportnummer. Für '<literal>security =
1367             ssl</literal>' ist 465 die Portnummer. Muss normalerweise nicht geändert werden.</para></listitem>
1368           </varlistentry>
1369
1370           <varlistentry>
1371             <term><varname>security</varname></term>
1372
1373             <listitem><para>Wahl der zu verwendenden Verschlüsselung der Verbindung mit dem Server. Standardwert ist
1374             '<literal>none</literal>', wodurch keine Verschlüsselung verwendet wird. Mit '<literal>tls</literal>' wird TLS-Verschlüsselung
1375             eingeschaltet, und mit '<literal>ssl</literal>' wird Verschlüsselung via SSL eingeschaltet. Achtung: Für
1376             '<literal>tls</literal>' und '<literal>ssl</literal>' werden zusätzliche Perl-Module benötigt (siehe unten).</para></listitem>
1377           </varlistentry>
1378
1379           <varlistentry>
1380             <term><varname>login</varname> und <varname>password</varname></term>
1381
1382             <listitem><para>Falls der E-Mail-Server eine Authentifizierung verlangt, so können mit diesen zwei Parametern der Benutzername
1383             und das Passwort angegeben werden. Wird Authentifizierung verwendet, so sollte aus Sicherheitsgründen auch eine Form von
1384             Verschlüsselung aktiviert werden.</para></listitem>
1385           </varlistentry>
1386         </variablelist>
1387
1388         <para>Wird Verschlüsselung über TLS oder SSL aktiviert, so werden zusätzliche Perl-Module benötigt. Diese sind:</para>
1389
1390         <itemizedlist>
1391           <listitem><para>TLS-Verschlüsselung: Modul <literal>Net::SSLGlue</literal> (Debian-Paketname
1392           <literal>libnet-sslglue-perl</literal>, Fedora Core: <literal>perl-Net-SSLGlue</literal>, openSUSE:
1393           <literal>perl-Net-SSLGlue</literal></para></listitem>
1394
1395           <listitem><para>SSL-Verschlüsselung: Modul <literal>Net::SMTP::SSL</literal> (Debian-Paketname
1396           <literal>libnet-smtp-ssl-perl</literal>, Fedora Core: <literal>perl-Net-SMTP-SSL</literal>, openSUSE:
1397           <literal>perl-Net-SMTP-SSL</literal></para></listitem>
1398         </itemizedlist>
1399       </sect2>
1400     </sect1>
1401
1402     <sect1 id="Drucken-mit-kivitendo">
1403       <title>Drucken mit kivitendo</title>
1404
1405       <para>Das Drucksystem von kivitendo benutzt von Haus aus LaTeX-Vorlagen.  Um drucken zu können, braucht der Server ein geeignetes
1406       LaTeX System. Am einfachsten ist dazu eine <literal>texlive</literal> Installation. Unter Debianoiden Betriebssystemen installiert man
1407       die Pakete mit:</para>
1408
1409       <para><programlisting>aptitude install texlive-base-bin texlive-latex-recommended texlive-fonts-recommended \
1410   texlive-latex-extra texlive-lang-german texlive-generic-extra</programlisting></para>
1411
1412       <para>TODO: RPM-Pakete.</para>
1413
1414       <para>kivitendo bringt drei alternative Vorlagensätze mit:</para>
1415       <itemizedlist>
1416         <listitem><para>Standard</para></listitem>
1417         <listitem><para>f-tex</para></listitem>
1418         <listitem><para>RB</para></listitem>
1419       </itemizedlist>
1420
1421       <sect2 id="Vorlagenverzeichnis-anlegen" xreflabel="Vorlagenverzeichnis anlegen">
1422         <title>Vorlagenverzeichnis anlegen</title>
1423         <para>Es lässt sich ein initialer Vorlagensatz erstellen. Die LaTeX-System-Abhängigkeiten hierfür kann man prüfen mit:</para>
1424
1425         <programlisting>./scripts/installation_check.pl -lv</programlisting>
1426
1427         <para>Der Angemmeldete Benutzer muss in einer Gruppe sein, die über das
1428               Recht "Konfiguration -> Mandantenverwaltung" verfügt. Siehe auch <xref linkend="Gruppen-anlegen"/>.
1429         </para>
1430         <para>Im Userbereich lässt sich unter:
1431         "<guimenu>System</guimenu> -&gt;
1432         <guisubmenu>Mandantenverwaltung</guisubmenu> -&gt; <guimenuitem>Verschiedenes</guimenuitem>" die Option
1433         "Neue Druckvorlagen aus Vorlagensatz erstellen" auswählen.</para>
1434
1435         <orderedlist>
1436           <listitem><para><option>Vorlagen auswählen</option>: Wählen Sie hier den Vorlagensatz aus, der kopiert werden soll
1437           (<filename>Standard</filename>, <filename>f-tex</filename> oder <filename>RB</filename>.)</para></listitem>
1438           <listitem><para><option>Neuer Name</option>: Der Verzeichnisname für den neuen Vorlagensatz. Dieser kann im Rahmen der üblichen
1439           Bedingungen für Verzeichnisnamen frei gewählt werden.</para></listitem>
1440         </orderedlist>
1441
1442         <para>Nach dem Speichern wird das Vorlagenverzeichnis angelegt und ist für den aktuellen Mandanten ausgewählt.
1443            Der gleiche Vorlagensatz kann, wenn er mal angelegt ist, bei mehreren Mandanten verwendet werden.
1444            Eventuell muessen Anpassungen (Logo, Erscheinungsbild, etc) noch vorgenommen werden. Den Ordner findet man im Dateisistem unter
1445            <filename>./templates/[Neuer Name]</filename></para>
1446
1447
1448       </sect2>
1449       <sect2 id="Vorlagen-Standard">
1450         <title>Standard</title>
1451
1452         <para>Der Standard-Vorlagensatz von Kivitendo. Wie unter <ulink url="http://demo.kivitendo.org">http://demo.kivitendo.org</ulink> zu
1453         sehen.</para>
1454
1455       </sect2>
1456
1457       <sect2 id="f-tex">
1458         <title>f-tex</title>
1459
1460         <para>Ein Vorlagensatz, der in wenigen Minuten alle Dokumente zur Verfügung stellt.</para>
1461
1462         <sect3 id="f-tex-Feature-Übersicht">
1463           <title>Feature-Übersicht</title>
1464           <itemizedlist>
1465             <listitem><para>Keine Redundanz. Es wird ein- und dieselbe LaTeX-Vorlage für alle briefartigen Dokumente verwendet. Also
1466             Angebot, Rechnung, Performarechnung, Lieferschein, aber eben nicht für Paketaufkleber etc..</para></listitem>
1467
1468             <listitem><para>Leichte Anpassung an das Firmen-Layout durch verwendung eines Hintergrund-PDF. Dieses kann leicht mit dem
1469             eigenen Lieblingsprogramm erstellt werden (Openoffice, Inkscape, Gimp, Adobe*)</para></listitem>
1470
1471             <listitem><para>Hintergrund-PDF umschaltbar auf "nur erste Seite" (Standard) oder "alle Seiten" (Option
1472             "<option>bgPdfFirstPageOnly</option>" in Datei <filename>letter.lco</filename>)</para></listitem>
1473
1474             <listitem><para>Hintergrund-PDF für Ausdruck auf bereits bedrucktem Briefpapier abschaltbar. Es wird dann nur bei per E-Mail
1475             versendeten Dokumenten eingebunden (Option "<option>bgPdfEmailOnly</option>" in Datei
1476             <filename>letter.lco</filename>).</para></listitem>
1477
1478             <listitem><para>Nutzung der Layout-Funktionen von LaTeX für Seitenumbruch, Wiederholung von Kopfzeilen, Zwischensummen
1479             etc. (danke an Kai-Martin Knaak für die Vorarbeit)</para></listitem>
1480
1481             <listitem><para>Anzeige des Empfängerlandes im Adressfeld nur, wenn es vom Land des eigenen Unternehmens abweicht (also die
1482             Rechnung das Land verlässt).</para></listitem>
1483
1484             <listitem><para>Multisprachfähig leicht um weitere Sprachen zu erweitern, alle Übersetzungen in der Datei
1485             <filename>translatinos.tex</filename>.</para></listitem>
1486
1487             <listitem><para>Auflistung von Bruttopreisen für Endverbraucher.</para></listitem>
1488           </itemizedlist>
1489         </sect3>
1490
1491         <sect3 id="f-tex-Installation">
1492           <title>Die Installation</title>
1493           <itemizedlist>
1494             <listitem><para>Vorlagenverzeichnis mit Option f-tex anlegen, siehe: <xref linkend="Vorlagenverzeichnis-anlegen"/>. Das
1495             Vorlagensystem funktioniert jetzt schon, hat allerdings noch einen Beispiel-Briefkopf.</para></listitem>
1496
1497             <listitem><para>Erstelle eine pdf-Hintergrund Datei und verlinke sie nach <filename>./letter_head.pdf</filename>.</para></listitem>
1498             <listitem><para>Editiere den Bereich "<option>settings</option>" in der datei <filename>letter.lco</filename>.</para></listitem>
1499           </itemizedlist>
1500
1501           <para>oder etwas Detaillierter:</para>
1502
1503           <para>
1504             Es wird eine Datei <filename>sample.lco</filename> erstellt und diese nach <filename>letter.lco</filename> verlinkt.  Eigentlich
1505             ist dies die Datei die für die Firmenspezifischen Anpassungen gedacht ist.  Da die Einstiegshürde in LaTeX nicht ganz niedrig
1506             ist, wird in dieser Datei auf ein Hintergrundpdf verwiesen. Ich empfehle über dieses PDF die persönlichen Layoutanpassungen
1507             vorzunehmen und <filename>sample.lco</filename> unverändert zu lassen. Die die Anpassung über eine
1508             <filename>*.lco</filename>-Datei die letztlich auf <filename>letter.lco</filename> verlinkt ist ist aber auch möglich.
1509           </para>
1510
1511           <para>
1512             Es wird eine Datei <filename>sample_head.pdf</filename> mit ausgeliefert, diese wird nach <filename>letter_head.pdf</filename>
1513             verlinkt. Damit gibt es schon mal eine Funktionsfähige Vorlage. Schau Dir nach Abschluss der Installation die Datei
1514             <filename>sample_haed.pdf</filename> an und erstelle ein entsprechendes PDF passend zum Briefkopf Deiner Firma, diese dann im
1515             Template Verzeichniss ablegen und statt <filename>sample_head.pdf</filename> nach <filename>letter_head.pdf</filename>
1516             verlinken.
1517           </para>
1518
1519           <para>
1520             letzlich muss <filename>letter_head.pdf</filename> auf das passende Hintergrund-PDF verweisen, welches gewünschten Briefkopf
1521             enthält. Bei Updates oder nach erneutem
1522           </para>
1523
1524           <para>
1525             Es wird eine Datei <filename>mydata.tex.example</filename> ausgeliefert, die nach <filename>mytdata.tex</filename> verlinkt
1526             ist. Bei verwendetem Hintergrund-PDF wird nur der Eintrag für das Land verwendet. Die Datei muss also nicht angefasst
1527             werden. Die Anderen Werte sind für das Modul 'lp' (Label Print in erp - zur Zeit nicht im öffentlichen Zweig).
1528           </para>
1529           <para>
1530             Alle Anpassungen zum Briefkopf, Fusszeilen, Firmenlogos, etc.  sollten über die Hintergrund-PDF-Datei oder die
1531             <filename>*.lco</filename>-Datei erfolgen.
1532           </para>
1533         </sect3>
1534
1535         <sect3 id="f-tex-Funktionsübersicht">
1536           <title>f-tex Funktionsübersicht</title>
1537           <para>
1538             Das Konzept von kivitendo sieht vor, für jedes Dokument (Auftragsbestätigung, Lieferschein, Rechnung, etc.) eine LaTeX-Vorlage
1539             vorzuhalten, dies ist sehr Wartungsunfreundlich. Auch das Einlesen einer einheitlichen Quelle für den Briefkopf bringt nur
1540             bedingte Vorteile, da hier leicht die Pflege der Artikel-Tabellen aus dem Ruder läuft. Bei dem vorliegenden Ansatz wird für alle
1541             briefartigen Dokumente mit Artikel-Tabellen eine einheitliche LaTeX-Vorlage verwendet, welche über Codeweichen die
1542             Besonderheiten der jeweiligen Dokumente Berücksichtigt.
1543           </para>
1544
1545           <itemizedlist>
1546             <listitem><para>Tabellen mit oder ohne Preis</para></listitem>
1547             <listitem><para>Sprache der Tabellenüberschriften etc.</para></listitem>
1548             <listitem><para>Anpassung der Bezugs-Zeile (z.B. Rechnungsnummer versus Angebotsnummer)</para></listitem>
1549             <listitem><para>Darstellung von Brutto oder Netto-Preisen in der Auflistung (Endverbraucher versus Gewerblicher
1550             Kunde)</para></listitem>
1551            </itemizedlist>
1552
1553            <para>Nachteil:</para>
1554
1555            <para>
1556              LaTeX hat ohnehin eine sehr steile Lehrnkurve. Die Datei <filename>letter.tex</filename> ist sehr komplex und verstärkt damit
1557              diesen Effekt noch einmal erheblich.  Wer LaTeX-Erfahrung hat, oder geübt ist Scriptsparachen nachzuvollziehen kann natürlich
1558              auch innerhalb der Tabellendarstellung gut persönliche Anpassungen vornehmen. Aber man kann sich hier bei Veränderungen sehr
1559              schnell häftig in den Fuss schiessen.
1560            </para>
1561
1562            <para>Wer nicht so tief in die Materie einsteigen will oder leicht zu frustrieren ist, sollte sein Hintergrund PDF auf Basis der
1563            mitglieferten Datei <filename>sample_head.pdf</filename> erstellen, und sich an der Form der dargestellten Tabellen wie sie
1564            ausgeliefert werden, erfreuen.
1565            </para>
1566
1567            <para>Kleiner Tipp: Nicht zu viel auf einmal wollen, lieber kleine kontinuierliche Schritte gehen.</para>
1568
1569         </sect3>
1570
1571         <sect3 id="f-tex-Bruttopreise">
1572           <title>Bruttopreise für Endverbraucher</title>
1573
1574                  <para>Der auszuweisende Bruttopreis wird innerhalb der LaTeX-Umgebung berechnet. Es gibt zwar ein Feld, um bei Aufträgen "alle
1575                  Preise Brutto" auszuwählen, aber:</para>
1576           <itemizedlist>
1577             <listitem>
1578               <para>hierfür müssen die Preise auch in Brutto in der Datenbank stehen (ja - das lässt sich über die Preisgruppen und die
1579               Zuordung einer Default-Preisgruppe handhaben)</para>
1580             </listitem>
1581             <listitem>
1582               <para>man darf beim Anlegen des Vorgangs nicht vergessen Dieses Häkchen zu setzen.  (das ist in der Praxis wenn man sowohl
1583               Endverbraucher- wie Gewerbekunden beliefert der eigentliche Knackpunkt)</para>
1584             </listitem>
1585           </itemizedlist>
1586
1587           <para>
1588             Es gibt mit f-tex eine weitere Alternative. Die Information ob Brutto oder Nettorechnung wird mit den Zahlarten
1589             verknüpft. Zahlarten bei denen Rechnungen, Angebote, etc, in Brutto ausgegeben werden sollen, enden mit "_E" (für
1590             Endverbraucher). Falls identische Zahlarten für Gewerbekunden und Endverbraucher vorhanden sind, legt man diese einfach doppelt
1591             an (einmal mit der Namensendung "_E"). Gewinn:</para>
1592
1593           <itemizedlist>
1594             <listitem><para>Die Entscheidung, ob Netopreise ausgewiesen werden, ist nicht mehr fix mit einer Preisliste Verbunden.</para></listitem>
1595             <listitem><para>Die Default-Zahlart kann im Kundendatensatz hinterlegt werden, und man muss nicht mehr daran denken, "alle Preise
1596             Netto" auszuwählen.</para></listitem>
1597             <listitem><para>Die Entscheidung, ob Netto- oder Bruttopreise ausgewiesen werden, kann direkt beim Drucken reviediert werden,
1598             ohne dass sich der Auftragswert ändert.</para></listitem>
1599           </itemizedlist>
1600         </sect3>
1601
1602         <sect3 id="f-tex-lieferadressen">
1603           <title>Lieferadressen</title>
1604
1605           <para>In Lieferscheinen kommen <varname>shipto*</varname>-Variablen im Adressfeld zum Einsatz. Wenn die
1606           <varname>shipto*</varname>-Variable leer ist, wird die entsprechende Adressvariable eingesetzt.  Wenn also die Lieferadresse in
1607           Straße, Hausnummer und Ort abweicht, müssen auch nur diese Felder in der Lieferadresse ausgefüllt werden. Für den Firmenname wird
1608           der Wert der Hauptadresse angezeigt.
1609           </para>
1610         </sect3>
1611       </sect2>
1612
1613       <sect2 id="Vorlagen-RB">
1614         <title>RB</title>
1615
1616         <para>Vollständiger Dokumentensatz mit alternativem Design</para>
1617         <para>Die konzeptionelle Idee wird <ulink
1618           url="http://www.kivitendo-support.de/vortraege/Lx-Office%20Anwendertreffen%20LaTeX-Druckvorlagen-Teil3-finale.pdf">hier</ulink>
1619           auf Folie 5 bis 10 vorgestellt, Detaileinstellungen dann im Readme.tex im Vorlagenverzeichnis.</para>
1620
1621       </sect2>
1622
1623       <sect2 id="allgemeine-hinweise-zu-latex">
1624         <title>Allgemeine Hinweise zu LaTeX Vorlagen</title>
1625         <para>In den allermeisten Installationen sollte drucken jetzt schon
1626         funktionieren. Sollte ein Fehler auftreten wirft TeX sehr lange
1627         Fehlerbeschreibungen, der eigentliche Fehler ist immer die erste Zeite
1628         die mit einem Ausrufezeichen anfängt. Häufig auftretende Fehler sind zum
1629         Beispiel:</para>
1630
1631         <itemizedlist>
1632           <listitem>
1633             <para>! LaTeX Error: File `eurosym.sty' not found. Die entsprechende
1634             LaTeX-Bibliothek wurde nicht gefunden. Das tritt vor allem bei
1635             Vorlagen aus der Community auf. Installieren Sie die entsprechenden
1636             Pakete.</para>
1637           </listitem>
1638           <listitem>
1639             <para>! Package inputenc Error: Unicode char \u8:... set up for
1640             use with LaTeX. Dieser Fehler tritt auf, wenn sie versuchen mit
1641             einer Standardinstallation exotische utf8 Zeichen zu drucken.
1642             TeXLive unterstützt von Haus nur romanische Schriften und muss mit
1643             diversen Tricks dazu gebracht werden andere Zeichen zu akzeptieren.
1644             Adere TeX Systeme wie XeTeX schaffen hier Abhilfe.</para>
1645           </listitem>
1646         </itemizedlist>
1647
1648         <para>Wird garkein Fehler angezeigt sondern nur der Name des Templates,
1649         heißt das normalerweise, dass das LaTeX Binary nicht gefunden wurde.
1650         Prüfen Sie den Namen in der Konfiguration (Standard:
1651         <literal>pdflatex</literal>), und stellen Sie sicher, dass pdflatex
1652         (oder das von Ihnen verwendete System) vom Webserver ausgeführt werden
1653         darf.</para>
1654
1655         <para>Wenn sich das Problem nicht auf Grund der ausgabe im Webbrowser verifizieren lässt:</para>
1656         <itemizedlist>
1657           <listitem>
1658              <para> editiere [kivitendo-home]/config/kivitendo.conf und ändere "keep_temp_files" auf 1</para>
1659              <para><programlisting>keep_temp_files = 1;</programlisting></para>
1660           </listitem>
1661           <listitem>
1662              <para>bei fastcgi oder mod_perl den Webserver neu Starten</para>
1663           </listitem>
1664           <listitem>
1665             <para>Nochmal einen Druckversuch im Webfrontend auslösen</para>
1666           </listitem>
1667           <listitem>
1668             <para>wechsele in das users Verzeichnis von kivitendo</para>
1669             <para><programlisting>cd [kivitendo-home]/users</programlisting></para>
1670           </listitem>
1671           <listitem>
1672             <para>LaTeX Suchpfad anpassen:</para>
1673             <para><programlisting>export TEXINPUTS=".:[kivitendo-home]/templates/[aktuelles_template_verzeichniss]:"</programlisting></para>
1674           </listitem>
1675           <listitem>
1676             <para>Finde herraus welche Datei kivitendo beim letzten Durchlauf erstellt hat</para>
1677             <para><programlisting>ls -lahtr ./1*.tex</programlisting></para>
1678             <para>Es sollte die letzte Datei ganz unten sein</para>
1679           </listitem>
1680           <listitem>
1681             <para>für besseren Hinweis auf Fehler texdatei nochmals übersetzen</para>
1682             <para><programlisting>pdflatex ./1*.tex</programlisting></para>
1683             <para>in der *.tex datei nach dem Fehler suchen.</para>
1684           </listitem>
1685         </itemizedlist>
1686       </sect2>
1687     </sect1>
1688
1689     <sect1 id="OpenDocument-Vorlagen">
1690       <title>OpenDocument-Vorlagen</title>
1691
1692       <para>kivitendo unterstützt die Verwendung von Vorlagen im
1693       OpenDocument-Format, wie es OpenOffice.org ab Version 2 erzeugt.
1694       kivitendo kann dabei sowohl neue OpenDocument-Dokumente als auch aus
1695       diesen direkt PDF-Dateien erzeugen. Um die Unterstützung von
1696       OpenDocument-Vorlagen zu aktivieren muss in der Datei
1697       <filename>config/kivitendo.conf</filename> die Variable
1698       <literal>opendocument</literal> im Abschnitt
1699       <literal>print_templates</literal> auf ‘<literal>1</literal>’ stehen.
1700       Dieses ist die Standardeinstellung.</para>
1701
1702       <para>Während die Erzeugung von reinen OpenDocument-Dateien keinerlei
1703       weitere Software benötigt, wird zur Umwandlung dieser Dateien in PDF
1704       OpenOffice.org benötigt. Soll dieses Feature genutzt werden, so muss
1705       neben OpenOffice.org ab Version 2 auch der “X virtual frame buffer”
1706       (xvfb) installiert werden. Bei Debian ist er im Paket “xvfb” enthalten.
1707       Andere Distributionen enthalten ihn in anderen Paketen.</para>
1708
1709       <para>Nach der Installation müssen in der Datei
1710       <filename>config/kivitendo.conf</filename> zwei weitere Variablen
1711       angepasst werden: <literal>openofficeorg_writer</literal> muss den
1712       vollständigen Pfad zur OpenOffice.org Writer-Anwendung enthalten.
1713       <literal>xvfb</literal> muss den Pfad zum “X virtual frame buffer”
1714       enthalten. Beide stehen im Abschnitt
1715       <literal>applications</literal>.</para>
1716
1717       <para>Zusätzlich gibt es zwei verschiedene Arten, wie kivitendo mit
1718       OpenOffice kommuniziert. Die erste Variante, die benutzt wird, wenn die
1719       Variable <literal>$openofficeorg_daemon</literal> gesetzt ist, startet
1720       ein OpenOffice, das auch nach der Umwandlung des Dokumentes gestartet
1721       bleibt. Bei weiteren Umwandlungen wird dann diese laufende Instanz
1722       benutzt. Der Vorteil ist, dass die Zeit zur Umwandlung deutlich
1723       reduziert wird, weil nicht für jedes Dokument ein OpenOffice gestartet
1724       werden muss. Der Nachteil ist, dass diese Methode Python und die
1725       Python-UNO-Bindings benötigt, die Bestandteil von OpenOffice 2
1726       sind.</para>
1727
1728       <note>
1729         <para>
1730           Für die Verbindung zu OpenOffice wird normalerweise der Python-Interpreter <filename>/usr/bin/python</filename> benutzt. Sollte
1731           dies nicht der richtige sein, so kann man mit zwei Konfigurationsvariablen entscheiden, welcher Python-Interpreter genutzt
1732           wird. Mit der Option <literal>python_uno</literal> aus dem Abschnitt <literal>applications</literal> wird der Interpreter selber
1733           festgelegt; sie steht standardmäßig auf dem eben erwähnten Wert <literal>/usr/bin/python</literal>.
1734         </para>
1735
1736         <para>
1737           Zusätzlich ist es möglich, Pfade anzugeben, in denen Python neben seinen normalen Suchpfaden ebenfalls nach Modulen gesucht wird,
1738           z.B. falls sich diese in einem gesonderten OpenOffice-Verzeichnis befinden. Diese zweite Variable heißt
1739           <literal>python_uno_path</literal> und befindet sich im Abschnitt <literal>environment</literal>. Sie ist standardmäßig
1740           leer. Werden hier mehrere Pfade angegeben, so müssen diese durch Doppelpunkte voneinander getrennt werden. Der Inhalt wird an den
1741           Python-Interpreter über die Umgebungsvariable <literal>PYTHONPATH</literal> übergeben.
1742         </para>
1743       </note>
1744
1745       <para>Ist <literal>$openofficeorg_daemon</literal> nicht gesetzt, so
1746       wird für jedes Dokument OpenOffice neu gestartet und die Konvertierung
1747       mit Hilfe eines Makros durchgeführt. Dieses Makro muss in der
1748       Dokumentenvorlage enthalten sein und
1749       “Standard.Conversion.ConvertSelfToPDF()” heißen. Die Beispielvorlage
1750       ‘<literal>templates/mastertemplates/German/invoice.odt</literal>’
1751       enthält ein solches Makro, das in jeder anderen Dokumentenvorlage
1752       ebenfalls enthalten sein muss.</para>
1753
1754       <para>Als letztes muss herausgefunden werden, welchen Namen
1755       OpenOffice.org Writer dem Verzeichnis mit den Benutzereinstellungen
1756       gibt. Unter Debian ist dies momentan
1757       <literal>~/.openoffice.org2</literal>. Sollte der Name bei Ihrer
1758       OpenOffice.org-Installation anders sein, so muss das Verzeichnis
1759       <literal>users/.openoffice.org2</literal> entsprechend umbenannt werden.
1760       Ist der Name z.B. einfach nur <literal>.openoffice</literal>, so wäre
1761       folgender Befehl auszuführen:</para>
1762
1763       <para><literal>mv users/.openoffice.org2
1764       users/.openoffice</literal></para>
1765
1766       <para>Dieses Verzeichnis, wie auch das komplette
1767       <literal>users</literal>-Verzeichnis, muss vom Webserver beschreibbar
1768       sein. Dieses wurde bereits erledigt (siehe <xref
1769       linkend="Manuelle-Installation-des-Programmpaketes" />), kann aber
1770       erneut überprüft werden, wenn die Konvertierung nach PDF
1771       fehlschlägt.</para>
1772     </sect1>
1773
1774     <sect1 id="config.eur">
1775       <title>Konfiguration zur Einnahmenüberschussrechnung/Bilanzierung:
1776       EUR</title>
1777
1778       <sect2 id="config.eur.introduction"
1779              xreflabel="Einführung in die Konfiguration zur EUR">
1780         <title>Einführung</title>
1781
1782         <para>kivitendo besaß bis inklusive Version 2.6.3 einen Konfigurationsparameter namens <varname>eur</varname>, der sich in der
1783         Konfigurationsdatei <filename>config/kivitendo.conf</filename> (damals noch <filename>config/lx_office.conf</filename>)
1784         befand. Somit galt er für alle Mandanten, die in dieser Installation benutzt wurden.</para>
1785
1786         <para>Mit der nachfolgenden Version wurde der Parameter zum Einen in
1787         die Mandantendatenbank verschoben und dabei auch gleich in drei
1788         Einzelparameter aufgeteilt, mit denen sich das Verhalten genauer
1789         steuern lässt.</para>
1790       </sect2>
1791
1792       <sect2 id="config.eur.parameters"
1793              xreflabel="Konfigurationsparameter für EUR">
1794         <title>Konfigurationsparameter</title>
1795
1796         <para>Es gibt drei Parameter, die die Gewinnermittlungsart,
1797         Versteuerungsart und die Warenbuchungsmethode regeln:</para>
1798
1799         <variablelist>
1800           <varlistentry>
1801             <term><varname>profit_determination</varname></term>
1802
1803             <listitem>
1804               <para>Dieser Parameter legt die Berechnungsmethode für die
1805               Gewinnermittlung fest. Er enthält entweder
1806               <literal>balance</literal> für
1807               Betriebsvermögensvergleich/Bilanzierung oder
1808               <literal>income</literal> für die
1809               Einnahmen-Überschuss-Rechnung.</para>
1810             </listitem>
1811           </varlistentry>
1812
1813           <varlistentry>
1814             <term><varname>accounting_method</varname></term>
1815
1816             <listitem>
1817               <para>Dieser Parameter steuert die Buchungs- und
1818               Berechnungsmethoden für die Versteuerungsart. Er enthält
1819               entweder <literal>accrual</literal> für die Soll-Versteuerung
1820               oder <literal>cash</literal> für die Ist-Versteuerung.</para>
1821             </listitem>
1822           </varlistentry>
1823
1824           <varlistentry>
1825             <term><varname>inventory_system</varname></term>
1826
1827             <listitem>
1828               <para>Dieser Parameter legt die Warenbuchungsmethode fest. Er
1829               enthält entweder <literal>perpetual</literal> für die
1830               Bestandsmethode oder <literal>periodic</literal> für die
1831               Aufwandsmethode.</para>
1832             </listitem>
1833           </varlistentry>
1834         </variablelist>
1835
1836         <para>Zum Vergleich der Funktionalität bis und nach 2.6.3:
1837         <varname>eur</varname> = 1 bedeutete Einnahmen-Überschuss-Rechnung,
1838         Ist-Versteuerung und Aufwandsmethode. <varname>eur</varname> = 0
1839         bedeutete hingegen Bilanzierung, Soll-Versteuerung und
1840         Bestandsmethode.</para>
1841
1842         <para>Die Konfiguration "<varname>eur</varname>" unter
1843         <varname>[system]</varname> in der <link
1844         linkend="config.config-file">Konfigurationsdatei</link>
1845         <filename>config/kivitendo.conf</filename> wird nun nicht mehr
1846         benötigt und kann entfernt werden. Dies muss manuell geschehen.</para>
1847       </sect2>
1848
1849       <sect2 id="config.eur.setting-parameters">
1850         <title>Festlegen der Parameter</title>
1851
1852         <para>Beim Anlegen eines neuen Mandanten bzw. einer neuen Datenbank in
1853         der Admininstration können diese Optionen nun unabhängig voneinander
1854         eingestellt werden.</para>
1855
1856         <para>Beim Upgrade bestehender Mandanten wird eur ausgelesen und die
1857         Variablen werden so gesetzt, daß sich an der Funktionalität nichts
1858         ändert.</para>
1859
1860         <para>Die aktuelle Konfiguration wird unter Nummernkreise und
1861         Standardkonten unter dem neuen Punkt "Einstellungen" (read-only)
1862         angezeigt. Unter <guimenu>System</guimenu>
1863         -&gt; <guisubmenu>Mandantenkonfiguration</guisubmenu> können
1864         die Einstellungen auch geändert werden. Dabei ist zu beachten,
1865         dass eine Änderung vorhandene Daten so belässt und damit
1866         evtl. die Ergebnisse verfälscht. Dies gilt vor Allem für die
1867         Warenbuchungsmethode (siehe auch
1868         <link linkend="config.eur.inventory-system-perpetual">
1869         Bemerkungen zu Bestandsmethode</link>).</para>
1870       </sect2>
1871
1872       <sect2 id="config.eur.inventory-system-perpetual">
1873         <title>Bemerkungen zu Bestandsmethode</title>
1874
1875         <para>Die Bestandsmethode ist eigentlich eine sehr elegante Methode,
1876         funktioniert in kivitendo aber nur unter bestimmten Bedingungen:
1877         Voraussetzung ist, daß auch immer alle Einkaufsrechnungen gepflegt
1878         werden, und man beim Jahreswechsel nicht mit einer leeren Datenbank
1879         anfängt, da bei jedem Verkauf anhand der gesamten Rechnungshistorie
1880         der Einkaufswert der Ware nach dem FIFO-Prinzip aus den
1881         Einkaufsrechnungen berechnet wird.</para>
1882
1883         <para>Die Bestandsmethode kann vom Prinzip her also nur funktioneren,
1884         wenn man mit den Buchungen bei Null anfängt, und man kann auch nicht
1885         im laufenden Betrieb von der Aufwandsmethode zur Bestandsmethode
1886         wechseln.</para>
1887       </sect2>
1888
1889       <sect2 id="config.eur.knonw-issues">
1890         <title>Bekannte Probleme</title>
1891
1892         <para>Bei bestimmten Berichten kann man derzeit noch inviduell
1893         einstellen, ob man nach Ist- oder Sollversteuerung auswertet, und es
1894         werden im Code Variablen wie $accrual oder $cash gesetzt. Diese
1895         Codestellen wurden noch nicht angepasst, sondern nur die, wo bisher
1896         die Konfigurationsvariable
1897         <varname>$::lx_office_conf{system}-&gt;{eur}</varname> ausgewertet
1898         wurde.</para>
1899
1900         <para>Es fehlen Hilfetext beim Neuanlegen eines Mandanten, was die
1901         Optionen bewirken, z.B. mit zwei Standardfällen.</para>
1902       </sect2>
1903     </sect1>
1904
1905     <sect1 id="config.skr04-update-3804">
1906       <title>SKR04 19% Umstellung für innergemeinschaftlichen Erwerb</title>
1907
1908       <sect2 id="config.skr04-update-3804.introduction">
1909         <title>Einführung</title>
1910
1911         <para>Die Umsatzsteuerumstellung auf 19% für SKR04 für die
1912         Steuerschlüssel "EU ohne USt-ID Nummer" ist erst 2010 erfolgt.
1913         kivitendo beinhaltet ein Upgradeskript, das das Konto 3804 automatisch
1914         erstellt und die Steuereinstellungen korrekt einstellt. Hat der
1915         Benutzer aber schon selber das Konto 3804 angelegt, oder gab es schon
1916         Buchungen im Zeitraum nach dem 01.01.2007 auf das Konto 3803, wird das
1917         Upgradeskript vorsichtshalber nicht ausgeführt, da der Benutzer sich
1918         vielleicht schon selbst geholfen hat und mit seinen Änderungen
1919         zufrieden ist. Die korrekten Einstellungen kann man aber auch per Hand
1920         ausführen. Nachfolgend werden die entsprechenden Schritte anhand von
1921         Screenshots dargestellt.</para>
1922
1923         <para>Für den Fall, daß Buchungen mit der Steuerschlüssel "EU ohne
1924         USt.-IdNr." nach dem 01.01.2007 erfolgt sind, ist davon auszugehen,
1925         dass diese mit dem alten Umsatzsteuersatz von 16% gebucht worden sind,
1926         und diese Buchungen sollten entsprechend kontrolliert werden.</para>
1927       </sect2>
1928
1929       <sect2 id="config.skr04-update-3804.create-chart">
1930         <title>Konto 3804 manuell anlegen</title>
1931
1932         <para>Die folgenden Schritte sind notwendig, um das Konto manuell
1933         anzulegen und zu konfigurieren. Zuerst wird in
1934         <guimenu>System</guimenu> -&gt;
1935         <guisubmenu>Kontenübersicht</guisubmenu> -&gt; <guimenuitem>Konto
1936         erfassen</guimenuitem> das Konto angelegt.</para>
1937
1938         <screenshot>
1939           <screeninfo>Konto 3804 erfassen</screeninfo>
1940
1941           <mediaobject>
1942             <imageobject>
1943               <imagedata fileref="images/skr04-update-3804/konto3804.png" />
1944             </imageobject>
1945           </mediaobject>
1946         </screenshot>
1947
1948         <para>
1949          Als Zweites muss Steuergruppe 13 für Konto 3803 angepasst werden. Dazu unter <guimenu>System</guimenu> -&gt;
1950          <guisubmenu>Steuern</guisubmenu> -&gt; <guimenuitem>Bearbeiten</guimenuitem> den Eintrag mit Steuerschlüssel 13 auswählen und ihn
1951          wie im folgenden Screenshot angezeigt anpassen.
1952         </para>
1953
1954         <screenshot>
1955           <screeninfo>Steuerschlüssel 13 für 3803 (16%) anpassen</screeninfo>
1956
1957           <mediaobject>
1958             <imageobject>
1959               <imagedata fileref="images/skr04-update-3804/steuer3803.png" />
1960             </imageobject>
1961           </mediaobject>
1962         </screenshot>
1963
1964         <para>
1965          Als Drittes wird ein neuer Eintrag mit Steuerschlüssel 13 für Konto 3804 (19%) angelegt. Dazu unter <guimenu>System</guimenu> -&gt;
1966          <guisubmenu>Steuern</guisubmenu> -&gt; <guimenuitem>Erfassen</guimenuitem> auswählen und die Werte aus dem Screenshot übernehmen.
1967         </para>
1968
1969         <screenshot>
1970           <screeninfo>Steuerschlüssel 13 für 3804 (19%) anlegen</screeninfo>
1971
1972           <mediaobject>
1973             <imageobject>
1974               <imagedata fileref="images/skr04-update-3804/steuer3804.png" />
1975             </imageobject>
1976           </mediaobject>
1977         </screenshot>
1978
1979         <para>
1980          Als Nächstes sind alle Konten anzupassen, die als Steuerautomatikkonto die 3803 haben, sodass sie ab dem 1.1.2007 auch
1981          Steuerautomatik auf 3804 bekommen. Dies betrifft in der Standardkonfiguration die Konten 4315 und 4726. Als Beispiel für 4315
1982          müssen Sie dazu unter <guimenu>System</guimenu> -&gt; <guisubmenu>Kontenübersicht</guisubmenu> -&gt; <guimenuitem>Konten
1983          anzeigen</guimenuitem> das Konto 4315 anklicken und die Einstellungen wie im Screenshot gezeigt vornehmen.
1984         </para>
1985
1986         <screenshot>
1987           <screeninfo>Konto 4315 anpassen</screeninfo>
1988
1989           <mediaobject>
1990             <imageobject>
1991               <imagedata fileref="images/skr04-update-3804/konto4315.png" />
1992             </imageobject>
1993           </mediaobject>
1994         </screenshot>
1995
1996         <para>
1997          Als Letztes sollte die Steuerliste unter <guimenu>System</guimenu> -&gt; <guisubmenu>Steuern</guisubmenu> -&gt;
1998          <guimenuitem>Bearbeiten</guimenuitem> kontrolliert werden. Zum Vergleich der Screenshot.
1999         </para>
2000
2001         <screenshot>
2002           <screeninfo>Steuerliste vergleichen</screeninfo>
2003
2004           <mediaobject>
2005             <imageobject>
2006               <imagedata fileref="images/skr04-update-3804/steuerliste.png" />
2007             </imageobject>
2008           </mediaobject>
2009         </screenshot>
2010       </sect2>
2011     </sect1>
2012     <sect1 id="bilanz">
2013      <title>Verhalten des Bilanzberichts</title>
2014       <para>
2015     Bis Version 3.0 wurde "closedto" ("Bücher schließen zum") als Grundlage für das
2016     Startdatum benutzt. Schließt man die Bücher allerdings monatsweise führt dies
2017     zu falschen Werten.</para>
2018     <para>In der Mandantenkonfiguration kann man dieses Verhalten genau einstellen indem man:</para>
2019   <itemizedlist>
2020    <listitem>
2021     <para>weiterhin closed_to benutzt (Default, es ändert sich nichts zu vorher)</para>
2022   </listitem>
2023    <listitem>
2024     <para>immer den Jahresanfang nimmt (1.1. relativ zum Stichtag)</para>
2025   </listitem>
2026    <listitem>
2027     <para>immer die letzte Eröffnungsbuchung als Startdatum nimmt</para>
2028        <para>- mit Jahresanfang als Alternative wenn es keine EB-Buchungen gibt</para>
2029       <para>- oder mit "alle Buchungen" als Alternative"</para>
2030    </listitem>
2031    <listitem>
2032      <para>mit Jahresanfang als Alternative wenn es keine EB-Buchungen gibt </para>
2033   </listitem>
2034    <listitem>
2035     <para>immer alle Buchungen seit Beginn der Datenbank nimmt</para>
2036   </listitem>
2037   </itemizedlist>
2038    Folgende Hinweise zu den Optionen:
2039     Das "Bücher schließen Datum" ist sinnvoll, wenn man nur komplette Jahre
2040     schließt. Bei Wirtschaftsjahr = Kalendarjahr entspricht dies aber auch
2041     Jahresanfang.
2042     "Alle Buchungen" kann z.B. sinnvoll sein wenn man ohne Jahresabschluß
2043     durchbucht.
2044     Eröffnungsbuchung mit "alle Buchungen" als Fallback ist z.B. sinnvoll, wenn man
2045     am sich Anfang des zweiten Buchungsjahres befindet, und noch keinen
2046     Jahreswechsel und auch noch keine EB-Buchungen hat.
2047     Bei den Optionen mit EB-Buchungen wird vorausgesetzt, daß diese immer am 1. Tag
2048     des Wirtschaftsjahres gebucht werden.
2049     Zur Sicherheit wird das Startdatum im Bilanzbericht jetzt zusätzlich zum
2050     Stichtag mit angezeigt. Das hilft auch bei der Kontrolle für den
2051     Abgleich mit der GuV.
2052     </sect1>
2053     <sect1 id="config.client">
2054       <title>Einstellungen pro Mandant</title>
2055
2056       <para>Einige Einstellungen können von einem Benutzer mit dem
2057       <link linkend="Zusammenhänge">Recht</link> "Administration
2058       (Für die Verwaltung der aktuellen Instanz aus einem Userlogin heraus)"
2059       gemacht werden. Diese Einstellungen sind dann für die aktuellen
2060       Mandanten-Datenbank gültig. Die Einstellungen sind
2061       unter <guimenu>System</guimenu>
2062       -&gt; <guisubmenu>Mandantenkonfiguration</guisubmenu> erreichbar.</para>
2063
2064       <para>Bitte beachten Sie die Hinweise zu den einzelnen
2065       Einstellungen. Einige Einstellungen sollten nicht ohne Weiteres
2066       im laufenden Betrieb geändert werden (siehe
2067       auch <link linkend="config.eur.inventory-system-perpetual">Bemerkungen zu
2068       Bestandsmethode</link>).</para>
2069
2070       <para>Die Einstellungen <literal>show_bestbefore</literal>
2071       und <literal>payments_changeable</literal> aus dem
2072       Abschnitt <literal>features</literal> und die Einstellungen im
2073       Abschnitt <literal>datev_check</literal> (sofern schon vorhanden)
2074       der <link linkend="config.config-file">kivitendo-Konfigurationsdatei</link>
2075       werden bei einem Datenbankupdate einer älteren Version automatisch
2076       übernommen. Diese Einträge können danach aus der Konfigurationsdatei
2077       entfernt werden.</para>
2078     </sect1>
2079
2080     <sect1 id="kivitendo-ERP-verwenden">
2081       <title>kivitendo ERP verwenden</title>
2082
2083       <para>Nach erfolgreicher Installation ist der Loginbildschirm unter
2084       folgender URL erreichbar:</para>
2085
2086       <para><ulink
2087       url="http://localhost/kivitendo-erp/login.pl">http://localhost/kivitendo-erp/login.pl</ulink></para>
2088
2089       <para>Die Administrationsseite erreichen Sie unter:</para>
2090
2091       <para><ulink
2092       url="http://localhost/kivitendo-erp/controller.pl?action=Admin/login">http://localhost/kivitendo-erp/controller.pl?action=Admin/login</ulink></para>
2093     </sect1>
2094   </chapter>
2095
2096   <chapter id="features" xreflabel="Features und Funktionen">
2097     <title>Features und Funktionen</title>
2098
2099     <sect1 id="features.periodic-invoices"
2100            xreflabel="Wiedekehrende Rechnungen">
2101       <title>Wiederkehrende Rechnungen</title>
2102
2103       <sect2 id="features.periodic-invoices.introduction"
2104              xreflabel="Einführung in wiederkehrende Rechnungen">
2105         <title>Einführung</title>
2106
2107         <para>Wiederkehrende Rechnungen werden als normale Aufträge definiert
2108         und konfiguriert, mit allen dazugehörigen Kunden- und Artikelangaben.
2109         Die konfigurierten Aufträge werden später automatisch in Rechnungen
2110         umgewandelt, so als ob man den Workflow benutzen würde, und auch die
2111         Auftragsnummer wird übernommen, sodass alle wiederkehrenden
2112         Rechnungen, die aus einem Auftrag erstellt wurden, später leicht
2113         wiederzufinden sind.</para>
2114       </sect2>
2115
2116       <sect2 id="features.periodic-invoices.configuration"
2117              xreflabel="Konfiguration von wiederkehrenden Rechnungen">
2118         <title>Konfiguration</title>
2119
2120         <para>Um einen Auftrag für wiederkehrende Rechnung zu konfigurieren,
2121         findet sich beim Bearbeiten des Auftrags ein neuer Knopf
2122         "Konfigurieren", der ein neues Fenster öffnet, in dem man die nötigen
2123         Parameter einstellen kann. Hinter dem Knopf wird außerdem noch
2124         angezeigt, ob der Auftrag als wiederkehrende Rechnung konfiguriert ist
2125         oder nicht.</para>
2126
2127         <para>Folgende Parameter kann man konfigurieren:</para>
2128
2129         <variablelist>
2130           <varlistentry>
2131             <term>Status</term>
2132
2133             <listitem>
2134               <para>Bei aktiven Rechnungen wird automatisch eine Rechnung
2135               erstellt, wenn die Periodizität erreicht ist (z.B. Anfang eines
2136               neuen Monats).</para>
2137
2138               <para>Ist ein Auftrag nicht aktiv, so werden für ihn auch keine
2139               wiederkehrenden Rechnungen erzeugt. Stellt man nach längerer
2140               nicht-aktiver Zeit einen Auftrag wieder auf aktiv, wird beim
2141               nächsten Periodenwechsel für alle Perioden, seit der letzten
2142               aktiven Periode, jeweils eine Rechnung erstellt. Möchte man dies
2143               verhindern, muss man vorher das Startdatum neu setzen.</para>
2144
2145               <para>Für gekündigte Aufträge werden nie mehr Rechnungen
2146               erstellt. Man kann sich diese Aufträge aber gesondert in den
2147               Berichten anzeigen lassen.</para>
2148             </listitem>
2149           </varlistentry>
2150
2151           <varlistentry>
2152             <term>Periodizität</term>
2153
2154             <listitem>
2155               <para>Ob monatlich, quartalsweise oder jährlich auf neue
2156               Rechnungen überprüft werden soll. Für jede Periode seit dem
2157               Startdatum wird überprüft, ob für die Periode (beginnend immer
2158               mit dem ersten Tag der Periode) schon eine Rechnung erstellt
2159               wurde. Unter Umständen können bei einem Startdatum in der
2160               Vergangenheit gleich mehrere Rechnungen erstellt werden.</para>
2161             </listitem>
2162           </varlistentry>
2163
2164           <varlistentry>
2165             <term>Buchen auf</term>
2166
2167             <listitem>
2168               <para>Das Forderungskonto, in der Regel "Forderungen aus
2169               Lieferungen und Leistungen". Das Gegenkonto ergibt sich aus den
2170               Buchungsgruppen der betreffenden Waren.</para>
2171             </listitem>
2172           </varlistentry>
2173
2174           <varlistentry>
2175             <term>Startdatum</term>
2176
2177             <listitem>
2178               <para>ab welchem Datum auf Rechnungserstellung geprüft werden
2179               soll</para>
2180             </listitem>
2181           </varlistentry>
2182
2183           <varlistentry>
2184             <term>Enddatum</term>
2185
2186             <listitem>
2187               <para>ab wann keine Rechnungen mehr erstellt werden
2188               sollen</para>
2189             </listitem>
2190           </varlistentry>
2191
2192           <varlistentry>
2193             <term>Automatische Verlängerung um x Monate</term>
2194
2195             <listitem>
2196               <para>Sollen die wiederkehrenden Rechnungen bei Erreichen des
2197               eingetragenen Enddatums weiterhin erstellt werden, so kann man
2198               hier die Anzahl der Monate eingeben, um die das Enddatum
2199               automatisch nach hinten geschoben wird.</para>
2200             </listitem>
2201           </varlistentry>
2202
2203           <varlistentry>
2204             <term>Drucken</term>
2205
2206             <listitem>
2207               <para>Sind Drucker konfiguriert, so kann man sich die erstellten
2208               Rechnungen auch gleich ausdrucken lassen.</para>
2209             </listitem>
2210           </varlistentry>
2211         </variablelist>
2212
2213         <para>Nach Erstellung der Rechnungen kann eine E-Mail mit
2214         Informationen zu den erstellten Rechnungen verschickt werden.
2215         Konfiguriert wird dies in der <link
2216         linkend="config.config-file.sections-parameters">Konfigurationsdatei</link>
2217         <filename>config/kivitendo.conf</filename> im Abschnitt
2218         <varname>[periodic_invoices]</varname>.</para>
2219       </sect2>
2220
2221       <sect2 id="features.periodic-invoices.variables">
2222         <title>Spezielle Variablen</title>
2223
2224         <para>
2225           Um die erzeugten Rechnungen individualisieren zu können, werden beim Umwandeln des Auftrags in eine Rechnung einige speziell
2226           formatierte Variablen durch für die jeweils aktuelle Abrechnungsperiode gültigen Werte ersetzt. Damit ist es möglich, z.B. den
2227           Abrechnungszeitraum explizit auszuweisen. Eine Variable hat dabei die Syntax <literal>&lt;%variablenname%&gt;</literal>.
2228         </para>
2229
2230         <para>
2231           Diese Variablen werden in den folgenden Elementen des Auftrags ersetzt:
2232         </para>
2233
2234         <itemizedlist>
2235           <listitem><para>Bemerkungen</para></listitem>
2236           <listitem><para>Interne Bemerkungen</para></listitem>
2237           <listitem><para>Vorgangsbezeichnung</para></listitem>
2238           <listitem><para>In den Beschreibungs- und Langtextfeldern aller Positionen</para></listitem>
2239         </itemizedlist>
2240
2241         <para>Die zur Verfügung stehenden Variablen sind die Folgenden:</para>
2242
2243         <variablelist>
2244           <varlistentry>
2245             <term><varname>&lt;%current_quarter%&gt;</varname>, <varname>&lt;%previous_quarter%&gt;</varname>, <varname>&lt;%next_quarter%&gt;</varname></term>
2246
2247             <listitem>
2248               <para>
2249                 Aktuelles, vorheriges und nächstes Quartal als Zahl zwischen <literal>1</literal> und <literal>4</literal>.
2250               </para>
2251             </listitem>
2252           </varlistentry>
2253
2254           <varlistentry>
2255             <term><varname>&lt;%current_month%&gt;</varname>, <varname>&lt;%previous_month%&gt;</varname>, <varname>&lt;%next_month%&gt;</varname></term>
2256
2257             <listitem>
2258               <para>
2259                 Aktueller, vorheriger und nächster Monat als Zahl zwischen <literal>1</literal> und <literal>12</literal>.
2260               </para>
2261             </listitem>
2262           </varlistentry>
2263
2264           <varlistentry>
2265             <term><varname>&lt;%current_month_long%&gt;</varname>, <varname>&lt;%previous_month_long%&gt;</varname>, <varname>&lt;%next_month_long%&gt;</varname></term>
2266
2267             <listitem>
2268               <para>
2269                 Aktueller, vorheriger und nächster Monat als Name (<literal>Januar</literal>, <literal>Februar</literal> etc.).
2270               </para>
2271             </listitem>
2272           </varlistentry>
2273
2274           <varlistentry>
2275             <term><varname>&lt;%current_year%&gt;</varname>, <varname>&lt;%previous_year%&gt;</varname>, <varname>&lt;%next_year%&gt;</varname></term>
2276
2277             <listitem>
2278               <para>
2279                 Aktuelles, vorheriges und nächstes Jahr als vierstellige Jahreszahl (<literal>2013</literal> etc.).
2280               </para>
2281             </listitem>
2282           </varlistentry>
2283
2284           <varlistentry>
2285             <term><varname>&lt;%period_start_date%&gt;</varname>, <varname>&lt;%period_end_date%&gt;</varname></term>
2286
2287             <listitem>
2288               <para>
2289                 Formatiertes Datum des ersten und letzten Tages im Abrechnungszeitraum (z.B. bei quartalsweiser Abrechnung und im ersten
2290                 Quartal von 2013 wären dies der <literal>01.01.2013</literal> und <literal>31.03.2013</literal>).
2291               </para>
2292             </listitem>
2293           </varlistentry>
2294         </variablelist>
2295       </sect2>
2296
2297       <sect2 id="features.periodic-invoices.reports">
2298         <title>Auflisten</title>
2299
2300         <para>Unter Verkauf-&gt;Berichte-&gt;Aufträge finden sich zwei neue
2301         Checkboxen, "Wiederkehrende Rechnungen aktiv" und "Wiederkehrende
2302         Rechnungen inaktiv", mit denen man sich einen Überglick über die
2303         wiederkehrenden Rechnungen verschaffen kann.</para>
2304       </sect2>
2305
2306       <sect2 id="features.periodic-invoices.task-server">
2307         <title>Erzeugung der eigentlichen Rechnungen</title>
2308
2309         <para>Die zeitliche und periodische Überprüfung, ob eine
2310         wiederkehrende Rechnung automatisch erstellt werden soll, geschieht
2311         durch den <link linkend="config.task-server">Taskserver</link>, einen
2312         externen Dienst, der automatisch beim Start des Servers gestartet
2313         werden sollte.</para>
2314       </sect2>
2315
2316       <sect2 id="features.periodic-invoices.create-for-current-month">
2317         <title>Erste Rechnung für aktuellen Monat erstellen</title>
2318
2319         <para>Will man im laufenden Monat eine monatlich wiederkehrende
2320         Rechnung inkl. des laufenden Monats starten, stellt man das Startdatum
2321         auf den Monatsanfang und wartet ein paar Minuten, bis der Taskserver
2322         den neu konfigurieren Auftrag erkennt und daraus eine Rechnung
2323         generiert hat. Alternativ setzt man das Startdatum auf den
2324         Monatsersten des Folgemonats und erstellt die erste Rechnung direkt
2325         manuell über den Workflow.</para>
2326       </sect2>
2327     </sect1>
2328         <sect1 id="dokumentenvorlagen-und-variablen">
2329       <title>Dokumentenvorlagen und verfügbare Variablen</title>
2330
2331       <sect2 id="dokumentenvorlagen-und-variablen.einführung">
2332         <title>Einführung</title>
2333
2334         <para>Dies ist eine Auflistung der Standard-Dokumentenvorlagen und
2335         aller zur Bearbeitung verfügbaren Variablen. Eine Variable wird in
2336         einer Vorlage durch ihren Inhalt ersetzt, wenn sie in der Form
2337         <function>&lt;%variablenname%&gt;</function> verwendet wird. Für
2338         LaTeX- und HTML-Vorlagen kann man die Form dieser Tags auch verändern
2339         (siehe <xref
2340         linkend="dokumentenvorlagen-und-variablen.tag-style" />).</para>
2341
2342         <para>Früher wurde hier nur über LaTeX gesprochen. Inzwischen
2343         unterstützt kivitendo aber auch OpenDocument-Vorlagen. Sofern es nicht
2344         ausdrücklich eingeschränkt wird, gilt das im Folgenden gesagte für
2345         alle Vorlagenarten.</para>
2346
2347         <para>Insgesamt sind technisch gesehen eine ganze Menge mehr Variablen
2348         verfügbar als hier aufgelistet werden. Die meisten davon können
2349         allerdings innerhalb einer solchen Vorlage nicht sinnvoll verwendet
2350         werden. Wenn eine Auflistung dieser Variablen gewollt ist, so kann
2351         diese wie folgt erhalten werden:</para>
2352
2353         <itemizedlist>
2354           <listitem>
2355             <para><filename>SL/Form.pm</filename> öffnen und am Anfang die
2356             Zeile "<command>use Data::Dumper;</command>" einfügen.</para>
2357           </listitem>
2358
2359           <listitem>
2360             <para>In <filename>Form.pm</filename> die Funktion
2361             <function>parse_template</function> suchen und hier die Zeile
2362             <command>print(STDERR Dumper($self));</command> einfügen.</para>
2363           </listitem>
2364
2365           <listitem>
2366             <para>Einmal per Browser die gewünschte Vorlage "benutzen", z.B.
2367             ein PDF für eine Rechnung erzeugen.</para>
2368           </listitem>
2369
2370           <listitem>
2371             <para>Im <filename>error.log</filename> Apache steht die Ausgabe
2372             der Variablen <varname>$self</varname> in der Form <varname>'key'
2373             =&gt; 'value',</varname>. Alle <varname>key</varname>s sind
2374             verfügbar.</para>
2375           </listitem>
2376         </itemizedlist>
2377       </sect2>
2378
2379       <sect2 id="dokumentenvorlagen-und-variablen.variablen-ausgeben">
2380         <title>Variablen ausgeben</title>
2381
2382         <para>Um eine Variable auszugeben, müssen sie einfach nur zwischen die
2383         Tags geschrieben werden, also z.B.
2384         <varname>&lt;%variablenname%&gt;</varname>.</para>
2385
2386         <para>Optional kann man auch mit Leerzeichen getrennte Flags angeben,
2387         die man aber nur selten brauchen wird. Die Syntax sieht also so aus:
2388         <varname>&lt;%variablenname FLAG1 FLAG2%&gt;</varname>. Momentan
2389         werden die folgenden Flags unterstützt:</para>
2390
2391         <itemizedlist>
2392           <listitem>
2393             <para><option>NOFORMAT</option> gilt nur für Zahlenwerte und gibt
2394             den Wert ohne Formatierung, also ohne Tausendertrennzeichen mit
2395             mit einem Punkt als Dezimaltrennzeichen aus. Nützlich z.B., wenn
2396             damit in der Vorlage z.B. von LaTeX gerechnet werden soll.</para>
2397           </listitem>
2398
2399           <listitem>
2400             <para><option>NOESCAPE</option> unterdrückt das Escapen von
2401             Sonderzeichen für die Vorlagensprache. Wenn also in einer
2402             Variablen bereits gültiger LaTeX-Code steht und dieser von LaTeX
2403             auch ausgewertet und nicht wortwörtlich angezeigt werden soll, so
2404             ist dieses Flag sinnvoll.</para>
2405           </listitem>
2406         </itemizedlist>
2407
2408         <para>Beispiel:</para>
2409
2410         <programlisting>&lt;%quototal NOFORMAT%&gt;</programlisting>
2411       </sect2>
2412
2413       <sect2 id="dokumentenvorlagen-und-variablen.verwendung-in-druckbefehlen">
2414         <title>Verwendung in Druckbefehlen</title>
2415
2416         <para>In der Admininstration können Drucker definiert werden. Auch im
2417         dort eingebbaren Druckbefehl können die hier aufgelisteten Variablen
2418         und Kontrollstrukturen verwendet werden. Ihr Inhalt wird dabei nach
2419         den Regeln der gängigen Shells formatiert, sodass Sonderzeichen wie
2420         <function>`...`</function> nicht zu unerwünschtem Verhalten
2421         führen.</para>
2422
2423         <para>Dies erlaubt z.B. die Definition eines Faxes als Druckerbefehl,
2424         für das die Telefonnummer eines Ansprechpartners als Teil der
2425         Kommandozeile verwendet wird. Für ein fiktives Kommando könnte das
2426         z.B. wie folgt aussehen:</para>
2427
2428         <programlisting>send_fax --number &lt;%if cp_phone2%&gt;&lt;%cp_phone2%&gt;&lt;%else%&gt;&lt;%cp_phone1%&gt;&lt;%end%&gt;</programlisting>
2429       </sect2>
2430
2431       <sect2 id="dokumentenvorlagen-und-variablen.tag-style"
2432              xreflabel="Anfang und Ende der Tags verändern">
2433         <title>Anfang und Ende der Tags verändern</title>
2434
2435         <para>Der Standardstil für Tags sieht vor, dass ein Tag mit dem
2436         Kleinerzeichen und einem Prozentzeichen beginnt und mit dem
2437         Prozentzeichen und dem Größerzeichen endet, beispielsweise
2438         <function>&lt;%customer%&gt;</function>. Da diese Form aber z.B. in
2439         LaTeX zu Problemen führen kann, weil das Prozentzeichen dort
2440         Kommentare einleitet, kann pro HTML- oder LaTeX-Dokumentenvorlage der
2441         Stil umgestellt werden.</para>
2442
2443         <para>Dazu werden in die Datei Zeilen geschrieben, die mit dem für das
2444         Format gültigen Kommentarzeichen anfangen, dann
2445         <function>config:</function> enthalten, die entsprechende Option
2446         setzen und bei HTML-Dokumentenvorlagen mit dem Kommentarendzeichen
2447         enden. Beispiel für LaTeX:</para>
2448
2449         <programlisting>% config: tag-style=($ $)</programlisting>
2450
2451         <para>Dies würde kivitendo dazu veranlassen, Variablen zu ersetzen,
2452         wenn sie wie folgt aussehen: <function>($customer$)</function>. Das
2453         äquivalente Beispiel für HTML-Dokumentenvorlagen sieht so aus:</para>
2454
2455         <programlisting>&lt;!-- config: tag-style=($ $) --&gt;</programlisting>
2456       </sect2>
2457
2458       <sect2 id="dokumentenvorlagen-und-variablen.zuordnung-dateinamen">
2459         <title>Zuordnung von den Dateinamen zu den Funktionen</title>
2460
2461         <para>Diese folgende kurze Auflistung zeigt, welche Vorlage bei
2462         welcher Funktion ausgelesen wird. Dabei ist die Dateiendung
2463         "<filename>.ext</filename>" geeignet zu ersetzen:
2464         "<filename>.tex</filename>" für LaTeX-Vorlagen und
2465         "<filename>.odt</filename>" für OpenDocument-Vorlagen.</para>
2466
2467         <variablelist>
2468           <varlistentry>
2469             <term><filename>bin_list.ext</filename></term>
2470
2471             <listitem>
2472               <para>Lagerliste</para>
2473             </listitem>
2474           </varlistentry>
2475
2476           <varlistentry>
2477             <term><filename>check.ext</filename></term>
2478
2479             <listitem>
2480               <para>?</para>
2481             </listitem>
2482           </varlistentry>
2483
2484           <varlistentry>
2485             <term><filename>invoice.ext</filename></term>
2486
2487             <listitem>
2488               <para>Rechnung</para>
2489             </listitem>
2490           </varlistentry>
2491
2492           <varlistentry>
2493             <term><filename>packing_list.ext</filename></term>
2494
2495             <listitem>
2496               <para>Packliste</para>
2497             </listitem>
2498           </varlistentry>
2499
2500           <varlistentry>
2501             <term><filename>pick_list.ext</filename></term>
2502
2503             <listitem>
2504               <para>Sammelliste</para>
2505             </listitem>
2506           </varlistentry>
2507
2508           <varlistentry>
2509             <term><filename>purchase_delivery_order.ext</filename></term>
2510
2511             <listitem>
2512               <para>Lieferschein (Einkauf)</para>
2513             </listitem>
2514           </varlistentry>
2515
2516           <varlistentry>
2517             <term><filename>purcharse_order.ext</filename></term>
2518
2519             <listitem>
2520               <para>Bestellung an Lieferanten</para>
2521             </listitem>
2522           </varlistentry>
2523
2524           <varlistentry>
2525             <term><filename>request_quotation.ext</filename></term>
2526
2527             <listitem>
2528               <para>Anfrage an Lieferanten</para>
2529             </listitem>
2530           </varlistentry>
2531
2532           <varlistentry>
2533             <term><filename>sales_delivery_order.ext</filename></term>
2534
2535             <listitem>
2536               <para>Lieferschein (Verkauf)</para>
2537             </listitem>
2538           </varlistentry>
2539
2540           <varlistentry>
2541             <term><filename>sales_order.ext</filename></term>
2542
2543             <listitem>
2544               <para>Bestellung</para>
2545             </listitem>
2546           </varlistentry>
2547
2548           <varlistentry>
2549             <term><filename>sales_quotation.ext</filename></term>
2550
2551             <listitem>
2552               <para>Angebot an Kunden</para>
2553             </listitem>
2554           </varlistentry>
2555
2556           <varlistentry>
2557             <term><filename>zahlungserinnerung.ext</filename></term>
2558
2559             <listitem>
2560               <para>Mahnung (Dateiname im Programm konfigurierbar)</para>
2561             </listitem>
2562           </varlistentry>
2563
2564           <varlistentry>
2565             <term><filename>zahlungserinnerung_invoice.ext</filename></term>
2566
2567             <listitem>
2568               <para>Rechnung über Mahngebühren (Dateiname im Programm
2569               konfigurierbar)</para>
2570             </listitem>
2571           </varlistentry>
2572         </variablelist>
2573       </sect2>
2574
2575       <sect2 id="dokumentenvorlagen-und-variablen.dateinamen-erweitert">
2576         <title>Sprache, Drucker und E-Mail</title>
2577
2578         <para>Angeforderte Sprache und Druckerkürzel in den Dateinamen mit
2579         eingearbeitet. So wird aus der Vorlage
2580         <filename>sales_order.ext</filename> bei Sprache
2581         <function>de</function> und Druckerkürzel <function>lpr2</function>
2582         der Vorlagenname <filename>sales_order_de_lpr2.ext</filename>.
2583         Zusätzlich können für E-Mails andere Vorlagen erstellt werden, diese
2584         bekommen dann noch das Kürzel <filename>_email</filename>, der
2585         vollständige Vorlagenname wäre dann
2586         <filename>sales_order_email_de_lpr2.ext</filename>. In allen Fällen
2587         kann eine Standarddatei <filename>default.ext</filename> hinterlegt
2588         werden. Diese wird verwendet, wenn keine der anderen Varianten
2589         gefunden wird.</para>
2590
2591         <para>Die vollständige Suchreihenfolge für einen Verkaufsauftrag mit
2592         der Sprache "de" und dem Drucker "lpr2", der per E-Mail im Format PDF
2593         verschickt wird, ist:</para>
2594
2595         <orderedlist>
2596           <listitem>
2597             <para><filename>sales_order_email_de_lpr2.tex</filename></para>
2598           </listitem>
2599
2600           <listitem>
2601             <para><filename>sales_order_de_lpr2.tex</filename></para>
2602           </listitem>
2603
2604           <listitem>
2605             <para><filename>sales_order.tex</filename></para>
2606           </listitem>
2607
2608           <listitem>
2609             <para><filename>default.tex</filename></para>
2610           </listitem>
2611         </orderedlist>
2612
2613         <para>Die kurzen Varianten dieser Vorlagentitel müssen dann entweder
2614         Standardwerte anzeigen, oder die angeforderten Werte selbst auswerten,
2615         siehe dazu <xref
2616         linkend="dokumentenvorlagen-und-variablen.allgemeine-variablen.meta" />.</para>
2617       </sect2>
2618
2619       <sect2 id="dokumentenvorlagen-und-variablen.allgemeine-variablen">
2620         <title>Allgemeine Variablen, die in allen Vorlagen vorhanden
2621         sind</title>
2622
2623         <sect3 id="dokumentenvorlagen-und-variablen.allgemeine-variablen.meta"
2624                xreflabel="Metainformationen zur angeforderten Vorlage">
2625           <title>Metainformationen zur angeforderten Vorlage</title>
2626
2627           <para>Diese Variablen liefern Informationen darüber welche Variante
2628           einer Vorlage der Benutzer angefragt hat. Sie sind nützlich für
2629           Vorlagenautoren, die aus einer zentralen Layoutvorlage die einzelnen
2630           Formulare einbinden möchten.</para>
2631
2632           <variablelist>
2633             <varlistentry>
2634               <term><varname>template_meta.formname</varname></term>
2635
2636               <listitem>
2637                 <para>Basisname der Vorlage. Identisch mit der <link
2638                 linkend="dokumentenvorlagen-und-variablen.zuordnung-dateinamen">Zurordnung
2639                 zu den Dateinamen</link> ohne die Erweiterung. Ein
2640                 Verkaufsauftrag enthält hier
2641                 <constant>sales_order</constant>.</para>
2642               </listitem>
2643             </varlistentry>
2644
2645             <varlistentry>
2646               <term><varname>template_meta.language.description</varname></term>
2647
2648               <listitem>
2649                 <para>Beschreibung der verwendeten Sprache</para>
2650               </listitem>
2651             </varlistentry>
2652
2653             <varlistentry>
2654               <term><varname>template_meta.language.template_code</varname></term>
2655
2656               <listitem>
2657                 <para>Vorlagenürzel der verwendeten Sprache, identisch mit dem
2658                 Kürzel das im Dateinamen verwendetet wird.</para>
2659               </listitem>
2660             </varlistentry>
2661
2662             <varlistentry>
2663               <term><varname>template_meta.language.output_numberformat</varname></term>
2664
2665               <listitem>
2666                 <para>Zahlenformat der verwendeten Sprache in der Form
2667                 "<constant>1.000,00</constant>". Experimentell! Nur
2668                 interessant für Vorlagen die mit unformatierten Werten
2669                 arbeiten.</para>
2670               </listitem>
2671             </varlistentry>
2672
2673             <varlistentry>
2674               <term><varname>template_meta.language.output_dateformat</varname></term>
2675
2676               <listitem>
2677                 <para>Datumsformat der verwendeten Sprache in der Form
2678                 "<constant>dd.mm.yyyy</constant>". Experimentell! Nur
2679                 interessant für Vorlagen die mit unformatierten Werten
2680                 arbeiten.</para>
2681               </listitem>
2682             </varlistentry>
2683
2684             <varlistentry>
2685               <term><varname>template_meta.format</varname></term>
2686
2687               <listitem>
2688                 <para>Das angeforderte Format. Kann im Moment die Werte
2689                 <constant>pdf</constant>, <constant>postscript</constant>,
2690                 <constant>html</constant>, <constant>opendocument</constant>,
2691                 <constant>opendocument_pdf</constant> und
2692                 <constant>excel</constant> enthalten.</para>
2693               </listitem>
2694             </varlistentry>
2695
2696             <varlistentry>
2697               <term><varname>template_meta.extension</varname></term>
2698
2699               <listitem>
2700                 <para>Dateierweiterung, wie im Dateinamen. Wird aus
2701                 <constant>format</constant> entschieden.</para>
2702               </listitem>
2703             </varlistentry>
2704
2705             <varlistentry>
2706               <term><varname>template_meta.media</varname></term>
2707
2708               <listitem>
2709                 <para>Ausgabemedium. Kann zur Zeit die Werte
2710                 <constant>screen</constant> für Bildschirm,
2711                 <constant>email</constant> für E-Mmail (triggert das
2712                 <constant>_email</constant> Kürzel im Dateinamen),
2713                 <constant>printer</constant> für Drucker, und
2714                 <constant>queue</constant> für Warteschlange enthalten.</para>
2715               </listitem>
2716             </varlistentry>
2717
2718             <varlistentry>
2719               <term><varname>template_meta.printer.description</varname></term>
2720
2721               <listitem>
2722                 <para>Beschreibung des ausgewählten Druckers</para>
2723               </listitem>
2724             </varlistentry>
2725
2726             <varlistentry>
2727               <term><varname>template_meta.printer.template_code</varname></term>
2728
2729               <listitem>
2730                 <para>Vorlagenürzel des ausgewählten Druckers, identisch mit
2731                 dem Kürzel das im Dateinamen verwendetet wird.</para>
2732               </listitem>
2733             </varlistentry>
2734
2735             <varlistentry>
2736               <term><varname>template_meta.tmpfile</varname></term>
2737
2738               <listitem>
2739                 <para>Datei-Prefix für temporäre Dateien.</para>
2740               </listitem>
2741             </varlistentry>
2742           </variablelist>
2743         </sect3>
2744
2745         <sect3 id="dokumentenvorlagen-und-variablen.allgemeine-variablen.kunden-lieferanten">
2746           <title>Stammdaten von Kunden und Lieferanten</title>
2747
2748           <variablelist>
2749             <varlistentry>
2750               <term><varname>account_number</varname></term>
2751
2752               <listitem>
2753                 <para>Kontonummer</para>
2754               </listitem>
2755             </varlistentry>
2756
2757             <varlistentry>
2758               <term><varname>bank</varname></term>
2759
2760               <listitem>
2761                 <para>Name der Bank</para>
2762               </listitem>
2763             </varlistentry>
2764
2765             <varlistentry>
2766               <term><varname>bank_code</varname></term>
2767
2768               <listitem>
2769                 <para>Bankleitzahl</para>
2770               </listitem>
2771             </varlistentry>
2772
2773             <varlistentry>
2774               <term><varname>bic</varname></term>
2775
2776               <listitem>
2777                 <para>Bank-Identifikations-Code (Bank Identifier Code,
2778                 BIC)</para>
2779               </listitem>
2780             </varlistentry>
2781
2782             <varlistentry>
2783               <term><varname>business</varname></term>
2784
2785               <listitem>
2786                 <para>Kunden-/Lieferantentyp</para>
2787               </listitem>
2788             </varlistentry>
2789
2790             <varlistentry>
2791               <term><varname>city</varname></term>
2792
2793               <listitem>
2794                 <para>Stadt</para>
2795               </listitem>
2796             </varlistentry>
2797
2798             <varlistentry>
2799               <term><varname>contact</varname></term>
2800
2801               <listitem>
2802                 <para>Kontakt</para>
2803               </listitem>
2804             </varlistentry>
2805
2806             <varlistentry>
2807               <term><varname>country</varname></term>
2808
2809               <listitem>
2810                 <para>Land</para>
2811               </listitem>
2812             </varlistentry>
2813
2814             <varlistentry>
2815               <term><varname>c_vendor_id</varname></term>
2816
2817               <listitem>
2818                 <para>Lieferantennummer beim Kunden (nur Kunden)</para>
2819               </listitem>
2820             </varlistentry>
2821
2822             <varlistentry>
2823               <term><varname>v_customer_id</varname></term>
2824
2825               <listitem>
2826                 <para>Kundennummer beim Lieferanten (nur Lieferanten)</para>
2827               </listitem>
2828             </varlistentry>
2829
2830             <varlistentry>
2831               <term><varname>cp_email</varname></term>
2832
2833               <listitem>
2834                 <para>Email des Ansprechpartners</para>
2835               </listitem>
2836             </varlistentry>
2837
2838             <varlistentry>
2839               <term><varname>cp_givenname</varname></term>
2840
2841               <listitem>
2842                 <para>Vorname des Ansprechpartners</para>
2843               </listitem>
2844             </varlistentry>
2845
2846             <varlistentry>
2847               <term><varname>cp_greeting</varname></term>
2848
2849               <listitem>
2850                 <para>Anrede des Ansprechpartners</para>
2851               </listitem>
2852             </varlistentry>
2853
2854             <varlistentry>
2855               <term><varname>cp_name</varname></term>
2856
2857               <listitem>
2858                 <para>Name des Ansprechpartners</para>
2859               </listitem>
2860             </varlistentry>
2861
2862             <varlistentry>
2863               <term><varname>cp_phone1</varname></term>
2864
2865               <listitem>
2866                 <para>Telefonnummer 1 des Ansprechpartners</para>
2867               </listitem>
2868             </varlistentry>
2869
2870             <varlistentry>
2871               <term><varname>cp_phone2</varname></term>
2872
2873               <listitem>
2874                 <para>Telefonnummer 2 des Ansprechpartners</para>
2875               </listitem>
2876             </varlistentry>
2877
2878             <varlistentry>
2879               <term><varname>cp_title</varname></term>
2880
2881               <listitem>
2882                 <para>Titel des Ansprechpartners</para>
2883               </listitem>
2884             </varlistentry>
2885
2886             <varlistentry>
2887               <term><varname>creditlimit</varname></term>
2888
2889               <listitem>
2890                 <para>Kreditlimit</para>
2891               </listitem>
2892             </varlistentry>
2893
2894             <varlistentry>
2895               <term><varname>customeremail</varname></term>
2896
2897               <listitem>
2898                 <para>Email des Kunden; nur für Kunden</para>
2899               </listitem>
2900             </varlistentry>
2901
2902             <varlistentry>
2903               <term><varname>customerfax</varname></term>
2904
2905               <listitem>
2906                 <para>Faxnummer des Kunden; nur für Kunden</para>
2907               </listitem>
2908             </varlistentry>
2909
2910             <varlistentry>
2911               <term><varname>customernotes</varname></term>
2912
2913               <listitem>
2914                 <para>Bemerkungen beim Kunden; nur für Kunden</para>
2915               </listitem>
2916             </varlistentry>
2917
2918             <varlistentry>
2919               <term><varname>customernumber</varname></term>
2920
2921               <listitem>
2922                 <para>Kundennummer; nur für Kunden</para>
2923               </listitem>
2924             </varlistentry>
2925
2926             <varlistentry>
2927               <term><varname>customerphone</varname></term>
2928
2929               <listitem>
2930                 <para>Telefonnummer des Kunden; nur für Kunden</para>
2931               </listitem>
2932             </varlistentry>
2933
2934             <varlistentry>
2935               <term><varname>discount</varname></term>
2936
2937               <listitem>
2938                 <para>Rabatt</para>
2939               </listitem>
2940             </varlistentry>
2941
2942             <varlistentry>
2943               <term><varname>email</varname></term>
2944
2945               <listitem>
2946                 <para>Emailadresse</para>
2947               </listitem>
2948             </varlistentry>
2949
2950             <varlistentry>
2951               <term><varname>fax</varname></term>
2952
2953               <listitem>
2954                 <para>Faxnummer</para>
2955               </listitem>
2956             </varlistentry>
2957
2958             <varlistentry>
2959               <term><varname>homepage</varname></term>
2960
2961               <listitem>
2962                 <para>Homepage</para>
2963               </listitem>
2964             </varlistentry>
2965
2966             <varlistentry>
2967               <term><varname>iban</varname></term>
2968
2969               <listitem>
2970                 <para>Internationale Kontonummer (International Bank Account
2971                 Number, IBAN)</para>
2972               </listitem>
2973             </varlistentry>
2974
2975             <varlistentry>
2976               <term><varname>language</varname></term>
2977
2978               <listitem>
2979                 <para>Sprache</para>
2980               </listitem>
2981             </varlistentry>
2982
2983             <varlistentry>
2984               <term><varname>name</varname></term>
2985
2986               <listitem>
2987                 <para>Firmenname</para>
2988               </listitem>
2989             </varlistentry>
2990
2991             <varlistentry>
2992               <term><varname>payment_description</varname></term>
2993
2994               <listitem>
2995                 <para>Name der Zahlart</para>
2996               </listitem>
2997             </varlistentry>
2998
2999             <varlistentry>
3000               <term><varname>payment_terms</varname></term>
3001
3002               <listitem>
3003                 <para>Zahlungskonditionen</para>
3004               </listitem>
3005             </varlistentry>
3006
3007             <varlistentry>
3008               <term><varname>phone</varname></term>
3009
3010               <listitem>
3011                 <para>Telefonnummer</para>
3012               </listitem>
3013             </varlistentry>
3014
3015             <varlistentry>
3016               <term><varname>shiptocity</varname></term>
3017
3018               <listitem>
3019                 <para>Stadt (Lieferadresse) <link
3020                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
3021               </listitem>
3022             </varlistentry>
3023
3024             <varlistentry>
3025               <term><varname>shiptocontact</varname></term>
3026
3027               <listitem>
3028                 <para>Kontakt (Lieferadresse) <link
3029                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
3030               </listitem>
3031             </varlistentry>
3032
3033             <varlistentry>
3034               <term><varname>shiptocountry</varname></term>
3035
3036               <listitem>
3037                 <para>Land (Lieferadresse) <link
3038                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
3039               </listitem>
3040             </varlistentry>
3041
3042             <varlistentry>
3043               <term><varname>shiptodepartment1</varname></term>
3044
3045               <listitem>
3046                 <para>Abteilung 1 (Lieferadresse) <link
3047                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
3048               </listitem>
3049             </varlistentry>
3050
3051             <varlistentry>
3052               <term><varname>shiptodepartment2</varname></term>
3053
3054               <listitem>
3055                 <para>Abteilung 2 (Lieferadresse) <link
3056                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
3057               </listitem>
3058             </varlistentry>
3059
3060             <varlistentry>
3061               <term><varname>shiptoemail</varname></term>
3062
3063               <listitem>
3064                 <para>Email (Lieferadresse) <link
3065                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
3066               </listitem>
3067             </varlistentry>
3068
3069             <varlistentry>
3070               <term><varname>shiptofax</varname></term>
3071
3072               <listitem>
3073                 <para>Fax (Lieferadresse) <link
3074                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
3075               </listitem>
3076             </varlistentry>
3077
3078             <varlistentry>
3079               <term><varname>shiptoname</varname></term>
3080
3081               <listitem>
3082                 <para>Firmenname (Lieferadresse) <link
3083                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
3084               </listitem>
3085             </varlistentry>
3086
3087             <varlistentry>
3088               <term><varname>shiptophone</varname></term>
3089
3090               <listitem>
3091                 <para>Telefonnummer (Lieferadresse) <link
3092                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
3093               </listitem>
3094             </varlistentry>
3095
3096             <varlistentry>
3097               <term><varname>shiptostreet</varname></term>
3098
3099               <listitem>
3100                 <para>Straße und Hausnummer (Lieferadresse) <link
3101                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
3102               </listitem>
3103             </varlistentry>
3104
3105             <varlistentry>
3106               <term><varname>shiptozipcode</varname></term>
3107
3108               <listitem>
3109                 <para>Postleitzahl (Lieferadresse) <link
3110                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
3111               </listitem>
3112             </varlistentry>
3113
3114             <varlistentry>
3115               <term><varname>street</varname></term>
3116
3117               <listitem>
3118                 <para>Straße und Hausnummer</para>
3119               </listitem>
3120             </varlistentry>
3121
3122             <varlistentry>
3123               <term><varname>taxnumber</varname></term>
3124
3125               <listitem>
3126                 <para>Steuernummer</para>
3127               </listitem>
3128             </varlistentry>
3129
3130             <varlistentry>
3131               <term><varname>ustid</varname></term>
3132
3133               <listitem>
3134                 <para>Umsatzsteuer-Identifikationsnummer</para>
3135               </listitem>
3136             </varlistentry>
3137
3138             <varlistentry>
3139               <term><varname>vendoremail</varname></term>
3140
3141               <listitem>
3142                 <para>Email des Lieferanten; nur für Lieferanten</para>
3143               </listitem>
3144             </varlistentry>
3145
3146             <varlistentry>
3147               <term><varname>vendorfax</varname></term>
3148
3149               <listitem>
3150                 <para>Faxnummer des Lieferanten; nur für Lieferanten</para>
3151               </listitem>
3152             </varlistentry>
3153
3154             <varlistentry>
3155               <term><varname>vendornotes</varname></term>
3156
3157               <listitem>
3158                 <para>Bemerkungen beim Lieferanten; nur für Lieferanten</para>
3159               </listitem>
3160             </varlistentry>
3161
3162             <varlistentry>
3163               <term><varname>vendornumber</varname></term>
3164
3165               <listitem>
3166                 <para>Lieferantennummer; nur für Lieferanten</para>
3167               </listitem>
3168             </varlistentry>
3169
3170             <varlistentry>
3171               <term><varname>vendorphone</varname></term>
3172
3173               <listitem>
3174                 <para>Telefonnummer des Lieferanten; nur für
3175                 Lieferanten</para>
3176               </listitem>
3177             </varlistentry>
3178
3179             <varlistentry>
3180               <term><varname>zipcode</varname></term>
3181
3182               <listitem>
3183                 <para>Postleitzahl</para>
3184               </listitem>
3185             </varlistentry>
3186           </variablelist>
3187
3188           <note id="dokumentenvorlagen-und-variablen.anmerkung-shipto">
3189             <para>Anmerkung: Sind die <varname>shipto*</varname>-Felder in den
3190             Stammdaten nicht eingetragen, so haben die Variablen
3191             <varname>shipto*</varname> den gleichen Wert wie die die
3192             entsprechenden Variablen der Lieferdaten. Das bedeutet, dass sich
3193             einige <varname>shipto*</varname>-Variablen so nicht in den
3194             Stammdaten wiederfinden sondern schlicht Kopien der
3195             Lieferdatenvariablen sind (z.B.
3196             <varname>shiptocontact</varname>).</para>
3197           </note>
3198         </sect3>
3199
3200         <sect3 id="dokumentenvorlagen-und-variablen.allgemein-bearbeiter">
3201           <title>Informationen über den Bearbeiter</title>
3202
3203           <variablelist>
3204             <varlistentry>
3205               <term><varname>employee_address</varname></term>
3206
3207               <listitem>
3208                 <para>Adressfeld</para>
3209               </listitem>
3210             </varlistentry>
3211
3212             <varlistentry>
3213               <term><varname>employee_businessnumber</varname></term>
3214
3215               <listitem>
3216                 <para>Firmennummer</para>
3217               </listitem>
3218             </varlistentry>
3219
3220             <varlistentry>
3221               <term><varname>employee_company</varname></term>
3222
3223               <listitem>
3224                 <para>Firmenname</para>
3225               </listitem>
3226             </varlistentry>
3227
3228             <varlistentry>
3229               <term><varname>employee_co_ustid</varname></term>
3230
3231               <listitem>
3232                 <para>Usatzsteuer-Identifikationsnummer</para>
3233               </listitem>
3234             </varlistentry>
3235
3236             <varlistentry>
3237               <term><varname>employee_duns</varname></term>
3238
3239               <listitem>
3240                 <para>DUNS-Nummer</para>
3241               </listitem>
3242             </varlistentry>
3243
3244             <varlistentry>
3245               <term><varname>employee_email</varname></term>
3246
3247               <listitem>
3248                 <para>Email</para>
3249               </listitem>
3250             </varlistentry>
3251
3252             <varlistentry>
3253               <term><varname>employee_fax</varname></term>
3254
3255               <listitem>
3256                 <para>Fax</para>
3257               </listitem>
3258             </varlistentry>
3259
3260             <varlistentry>
3261               <term><varname>employee_name</varname></term>
3262
3263               <listitem>
3264                 <para>voller Name</para>
3265               </listitem>
3266             </varlistentry>
3267
3268             <varlistentry>
3269               <term><varname>employee_signature</varname></term>
3270
3271               <listitem>
3272                 <para>Signatur</para>
3273               </listitem>
3274             </varlistentry>
3275
3276             <varlistentry>
3277               <term><varname>employee_taxnumber</varname></term>
3278
3279               <listitem>
3280                 <para>Steuernummer</para>
3281               </listitem>
3282             </varlistentry>
3283
3284             <varlistentry>
3285               <term><varname>employee_tel</varname></term>
3286
3287               <listitem>
3288                 <para>Telefonnummer</para>
3289               </listitem>
3290             </varlistentry>
3291           </variablelist>
3292         </sect3>
3293
3294         <sect3 id="dokumentenvorlagen-und-variablen.allgemein-verkaeufer">
3295           <title>Informationen über den Verkäufer</title>
3296
3297           <variablelist>
3298             <varlistentry>
3299               <term><varname>salesman_address</varname></term>
3300
3301               <listitem>
3302                 <para>Adressfeld</para>
3303               </listitem>
3304             </varlistentry>
3305
3306             <varlistentry>
3307               <term><varname>salesman_businessnumber</varname></term>
3308
3309               <listitem>
3310                 <para>Firmennummer</para>
3311               </listitem>
3312             </varlistentry>
3313
3314             <varlistentry>
3315               <term><varname>salesman_company</varname></term>
3316
3317               <listitem>
3318                 <para>Firmenname</para>
3319               </listitem>
3320             </varlistentry>
3321
3322             <varlistentry>
3323               <term><varname>salesman_co_ustid</varname></term>
3324
3325               <listitem>
3326                 <para>Usatzsteuer-Identifikationsnummer</para>
3327               </listitem>
3328             </varlistentry>
3329
3330             <varlistentry>
3331               <term><varname>salesman_duns</varname></term>
3332
3333               <listitem>
3334                 <para>DUNS-Nummer</para>
3335               </listitem>
3336             </varlistentry>
3337
3338             <varlistentry>
3339               <term><varname>salesman_email</varname></term>
3340
3341               <listitem>
3342                 <para>Email</para>
3343               </listitem>
3344             </varlistentry>
3345
3346             <varlistentry>
3347               <term><varname>salesman_fax</varname></term>
3348
3349               <listitem>
3350                 <para>Fax</para>
3351               </listitem>
3352             </varlistentry>
3353
3354             <varlistentry>
3355               <term><varname>salesman_name</varname></term>
3356
3357               <listitem>
3358                 <para>voller Name</para>
3359               </listitem>
3360             </varlistentry>
3361
3362             <varlistentry>
3363               <term><varname>salesman_signature</varname></term>
3364
3365               <listitem>
3366                 <para>Signatur</para>
3367               </listitem>
3368             </varlistentry>
3369
3370             <varlistentry>
3371               <term><varname>salesman_taxnumber</varname></term>
3372
3373               <listitem>
3374                 <para>Steuernummer</para>
3375               </listitem>
3376             </varlistentry>
3377
3378             <varlistentry>
3379               <term><varname>salesman_tel</varname></term>
3380
3381               <listitem>
3382                 <para>Telefonnummer</para>
3383               </listitem>
3384             </varlistentry>
3385           </variablelist>
3386         </sect3>
3387
3388         <sect3 id="dokumentenvorlagen-und-variablen.allgemein-steuern">
3389           <title>Variablen für die einzelnen Steuern</title>
3390
3391           <variablelist>
3392             <varlistentry>
3393               <term><varname>tax</varname></term>
3394
3395               <listitem>
3396                 <para>Steuer</para>
3397               </listitem>
3398             </varlistentry>
3399
3400             <varlistentry>
3401               <term><varname>taxbase</varname></term>
3402
3403               <listitem>
3404                 <para>zu versteuernder Betrag</para>
3405               </listitem>
3406             </varlistentry>
3407
3408             <varlistentry>
3409               <term><varname>taxdescription</varname></term>
3410
3411               <listitem>
3412                 <para>Name der Steuer</para>
3413               </listitem>
3414             </varlistentry>
3415
3416             <varlistentry>
3417               <term><varname>taxrate</varname></term>
3418
3419               <listitem>
3420                 <para>Steuersatz</para>
3421               </listitem>
3422             </varlistentry>
3423           </variablelist>
3424         </sect3>
3425
3426         <sect3 id="dokumentenvorlagen-und-variablen.allgemein-lieferbedingungen">
3427           <title>Variablen für Lieferbedingungen</title>
3428
3429           <variablelist>
3430             <varlistentry>
3431               <term><varname>delivery_term</varname></term>
3432               <listitem><para>Datenbank-Objekt der Lieferbedingung</para></listitem>
3433             </varlistentry>
3434             <varlistentry>
3435               <term><varname>delivery_term.description</varname></term>
3436               <listitem><para>Beschreibung der Lieferbedingung</para></listitem>
3437             </varlistentry>
3438             <varlistentry>
3439               <term><varname>delivery_term.long_description</varname></term>
3440               <listitem><para>Langtext bzw. übersetzter Langtext der Lieferbedingung</para></listitem>
3441             </varlistentry>
3442           </variablelist>
3443         </sect3>
3444       </sect2>
3445
3446       <sect2 id="dokumentenvorlagen-und-variablen.invoice">
3447         <title>Variablen in Rechnungen</title>
3448
3449         <sect3 id="dokumentenvorlagen-und-variablen.invoice-allgemein">
3450           <title>Allgemeine Variablen</title>
3451
3452           <variablelist>
3453             <varlistentry>
3454               <term><varname>creditremaining</varname></term>
3455
3456               <listitem>
3457                 <para>Verbleibender Kredit</para>
3458               </listitem>
3459             </varlistentry>
3460
3461             <varlistentry>
3462               <term><varname>currency</varname></term>
3463
3464               <listitem>
3465                 <para>Währung</para>
3466               </listitem>
3467             </varlistentry>
3468
3469             <varlistentry>
3470               <term><varname>cusordnumber</varname></term>
3471
3472               <listitem>
3473                 <para>Bestellnummer beim Kunden</para>
3474               </listitem>
3475             </varlistentry>
3476
3477             <varlistentry>
3478               <term><varname>deliverydate</varname></term>
3479
3480               <listitem>
3481                 <para>Lieferdatum</para>
3482               </listitem>
3483             </varlistentry>
3484
3485             <varlistentry>
3486               <term><varname>duedate</varname></term>
3487
3488               <listitem>
3489                 <para>Fälligkeitsdatum</para>
3490               </listitem>
3491             </varlistentry>
3492
3493             <varlistentry>
3494               <term><varname>globalprojectnumber</varname></term>
3495
3496               <listitem>
3497                 <para>Projektnummer des ganzen Beleges</para>
3498               </listitem>
3499             </varlistentry>
3500
3501             <varlistentry>
3502               <term><varname>globalprojectdescription</varname></term>
3503
3504               <listitem>
3505                 <para>Projekbeschreibung des ganzen Beleges</para>
3506               </listitem>
3507             </varlistentry>
3508
3509             <varlistentry>
3510               <term><varname>intnotes</varname></term>
3511
3512               <listitem>
3513                 <para>Interne Bemerkungen</para>
3514               </listitem>
3515             </varlistentry>
3516
3517             <varlistentry>
3518               <term><varname>invdate</varname></term>
3519
3520               <listitem>
3521                 <para>Rechnungsdatum</para>
3522               </listitem>
3523             </varlistentry>
3524
3525             <varlistentry>
3526               <term><varname>invnumber</varname></term>
3527
3528               <listitem>
3529                 <para>Rechnungsnummer</para>
3530               </listitem>
3531             </varlistentry>
3532
3533             <varlistentry>
3534               <term><varname>invtotal</varname></term>
3535
3536               <listitem>
3537                 <para>gesamter Rechnungsbetrag</para>
3538               </listitem>
3539             </varlistentry>
3540
3541             <varlistentry>
3542               <term><varname>notes</varname></term>
3543
3544               <listitem>
3545                 <para>Bemerkungen der Rechnung</para>
3546               </listitem>
3547             </varlistentry>
3548
3549             <varlistentry>
3550               <term><varname>orddate</varname></term>
3551
3552               <listitem>
3553                 <para>Auftragsdatum</para>
3554               </listitem>
3555             </varlistentry>
3556
3557             <varlistentry>
3558               <term><varname>ordnumber</varname></term>
3559
3560               <listitem>
3561                 <para>Auftragsnummer, wenn die Rechnung aus einem Auftrag
3562                 erstellt wurde</para>
3563               </listitem>
3564             </varlistentry>
3565
3566             <varlistentry>
3567               <term><varname>payment_description</varname></term>
3568
3569               <listitem>
3570                 <para>Name der Zahlart</para>
3571               </listitem>
3572             </varlistentry>
3573
3574             <varlistentry>
3575               <term><varname>payment_terms</varname></term>
3576
3577               <listitem>
3578                 <para>Zahlungskonditionen</para>
3579               </listitem>
3580             </varlistentry>
3581
3582             <varlistentry>
3583               <term><varname>quodate</varname></term>
3584
3585               <listitem>
3586                 <para>Angebotsdatum</para>
3587               </listitem>
3588             </varlistentry>
3589
3590             <varlistentry>
3591               <term><varname>quonumber</varname></term>
3592
3593               <listitem>
3594                 <para>Angebotsnummer</para>
3595               </listitem>
3596             </varlistentry>
3597
3598             <varlistentry>
3599               <term><varname>shippingpoint</varname></term>
3600
3601               <listitem>
3602                 <para>Versandort</para>
3603               </listitem>
3604             </varlistentry>
3605
3606             <varlistentry>
3607               <term><varname>shipvia</varname></term>
3608
3609               <listitem>
3610                 <para>Transportmittel</para>
3611               </listitem>
3612             </varlistentry>
3613
3614             <varlistentry>
3615               <term><varname>subtotal</varname></term>
3616
3617               <listitem>
3618                 <para>Zwischensumme aller Posten ohne Steuern</para>
3619               </listitem>
3620             </varlistentry>
3621
3622             <varlistentry>
3623               <term><varname>total</varname></term>
3624
3625               <listitem>
3626                 <para>Restsumme der Rechnung (Summe abzüglich bereits
3627                 bezahlter Posten)</para>
3628               </listitem>
3629             </varlistentry>
3630
3631             <varlistentry>
3632               <term><varname>transaction_description</varname></term>
3633
3634               <listitem>
3635                 <para>Vorgangsbezeichnung</para>
3636               </listitem>
3637             </varlistentry>
3638
3639             <varlistentry>
3640               <term><varname>transdate</varname></term>
3641
3642               <listitem>
3643                 <para>Auftragsdatum wenn die Rechnung aus einem Auftrag
3644                 erstellt wurde</para>
3645               </listitem>
3646             </varlistentry>
3647           </variablelist>
3648         </sect3>
3649
3650         <sect3 id="dokumentenvorlagen-und-variablen.invoice-posten">
3651           <title>Variablen für jeden Posten auf der Rechnung</title>
3652
3653           <variablelist>
3654             <varlistentry>
3655               <term><varname>bin</varname></term>
3656
3657               <listitem>
3658                 <para>Stellage</para>
3659               </listitem>
3660             </varlistentry>
3661
3662             <varlistentry>
3663               <term><varname>description</varname></term>
3664
3665               <listitem>
3666                 <para>Artikelbeschreibung</para>
3667               </listitem>
3668             </varlistentry>
3669
3670             <varlistentry>
3671               <term><varname>discount</varname></term>
3672
3673               <listitem>
3674                 <para>Rabatt als Betrag</para>
3675               </listitem>
3676             </varlistentry>
3677
3678             <varlistentry>
3679               <term><varname>discount_sub</varname></term>
3680
3681               <listitem>
3682                 <para>Zwischensumme mit Rabatt</para>
3683               </listitem>
3684             </varlistentry>
3685
3686             <varlistentry>
3687               <term><varname>drawing</varname></term>
3688
3689               <listitem>
3690                 <para>Zeichnung</para>
3691               </listitem>
3692             </varlistentry>
3693
3694             <varlistentry>
3695               <term><varname>ean</varname></term>
3696
3697               <listitem>
3698                 <para>EAN-Code</para>
3699               </listitem>
3700             </varlistentry>
3701
3702             <varlistentry>
3703               <term><varname>image</varname></term>
3704
3705               <listitem>
3706                 <para>Grafik</para>
3707               </listitem>
3708             </varlistentry>
3709
3710             <varlistentry>
3711               <term><varname>linetotal</varname></term>
3712
3713               <listitem>
3714                 <para>Zeilensumme (Anzahl * Einzelpreis)</para>
3715               </listitem>
3716             </varlistentry>
3717
3718             <varlistentry>
3719               <term><varname>longdescription</varname></term>
3720
3721               <listitem>
3722                 <para>Langtext</para>
3723               </listitem>
3724             </varlistentry>
3725
3726             <varlistentry>
3727               <term><varname>microfiche</varname></term>
3728
3729               <listitem>
3730                 <para>Mikrofilm</para>
3731               </listitem>
3732             </varlistentry>
3733
3734             <varlistentry>
3735               <term><varname>netprice</varname></term>
3736
3737               <listitem>
3738                 <para>Nettopreis</para>
3739               </listitem>
3740             </varlistentry>
3741
3742             <varlistentry>
3743               <term><varname>nodiscount_linetotal</varname></term>
3744
3745               <listitem>
3746                 <para>Zeilensumme ohne Rabatt</para>
3747               </listitem>
3748             </varlistentry>
3749
3750             <varlistentry>
3751               <term><varname>nodiscount_sub</varname></term>
3752
3753               <listitem>
3754                 <para>Zwischensumme ohne Rabatt</para>
3755               </listitem>
3756             </varlistentry>
3757
3758             <varlistentry>
3759               <term><varname>number</varname></term>
3760
3761               <listitem>
3762                 <para>Artikelnummer</para>
3763               </listitem>
3764             </varlistentry>
3765
3766             <varlistentry>
3767               <term><varname>ordnumber_oe</varname></term>
3768
3769               <listitem>
3770                 <para>Auftragsnummer des Originalauftrags, wenn die Rechnung
3771                 aus einem Sammelauftrag erstellt wurde</para>
3772               </listitem>
3773             </varlistentry>
3774
3775             <varlistentry>
3776               <term><varname>p_discount</varname></term>
3777
3778               <listitem>
3779                 <para>Rabatt in Prozent</para>
3780               </listitem>
3781             </varlistentry>
3782
3783             <varlistentry>
3784               <term><varname>partnotes</varname></term>
3785
3786               <listitem>
3787                 <para>Die beim Artikel gespeicherten Bemerkungen</para>
3788               </listitem>
3789             </varlistentry>
3790
3791             <varlistentry>
3792               <term><varname>partsgroup</varname></term>
3793
3794               <listitem>
3795                 <para>Warengruppe</para>
3796               </listitem>
3797             </varlistentry>
3798
3799             <varlistentry>
3800               <term><varname>price_factor</varname></term>
3801
3802               <listitem>
3803                 <para>Der Preisfaktor als Zahl, sofern einer eingestellt
3804                 ist</para>
3805               </listitem>
3806             </varlistentry>
3807
3808             <varlistentry>
3809               <term><varname>price_factor_name</varname></term>
3810
3811               <listitem>
3812                 <para>Der Name des Preisfaktors, sofern einer eingestellt
3813                 ist</para>
3814               </listitem>
3815             </varlistentry>
3816
3817             <varlistentry>
3818               <term><varname>projectnumber</varname></term>
3819
3820               <listitem>
3821                 <para>Projektnummer</para>
3822               </listitem>
3823             </varlistentry>
3824
3825             <varlistentry>
3826               <term><varname>projectdescription</varname></term>
3827
3828               <listitem>
3829                 <para>Projektbeschreibung</para>
3830               </listitem>
3831             </varlistentry>
3832
3833             <varlistentry>
3834               <term><varname>qty</varname></term>
3835
3836               <listitem>
3837                 <para>Anzahl</para>
3838               </listitem>
3839             </varlistentry>
3840
3841             <varlistentry>
3842               <term><varname>reqdate</varname></term>
3843
3844               <listitem>
3845                 <para>Lieferdatum</para>
3846               </listitem>
3847             </varlistentry>
3848
3849             <varlistentry>
3850               <term><varname>runningnumber</varname></term>
3851
3852               <listitem>
3853                 <para>Position auf der Rechnung (1, 2, 3...)</para>
3854               </listitem>
3855             </varlistentry>
3856
3857             <varlistentry>
3858               <term><varname>sellprice</varname></term>
3859
3860               <listitem>
3861                 <para>Verkaufspreis</para>
3862               </listitem>
3863             </varlistentry>
3864
3865             <varlistentry>
3866               <term><varname>serialnumber</varname></term>
3867
3868               <listitem>
3869                 <para>Seriennummer</para>
3870               </listitem>
3871             </varlistentry>
3872
3873             <varlistentry>
3874               <term><varname>tax_rate</varname></term>
3875
3876               <listitem>
3877                 <para>Steuersatz</para>
3878               </listitem>
3879             </varlistentry>
3880
3881             <varlistentry>
3882               <term><varname>transdate_oe</varname></term>
3883
3884               <listitem>
3885                 <para>Auftragsdatum des Originalauftrags, wenn die Rechnung
3886                 aus einem Sammelauftrag erstellt wurde</para>
3887               </listitem>
3888             </varlistentry>
3889
3890             <varlistentry>
3891               <term><varname>unit</varname></term>
3892
3893               <listitem>
3894                 <para>Einheit</para>
3895               </listitem>
3896             </varlistentry>
3897
3898             <varlistentry>
3899               <term><varname>weight</varname></term>
3900
3901               <listitem>
3902                 <para>Gewicht</para>
3903               </listitem>
3904             </varlistentry>
3905           </variablelist>
3906
3907           <para>Für jeden Posten gibt es ein Unterarray mit den Informationen
3908           über Lieferanten und Lieferantenartikelnummer. Diese müssen mit
3909           einer <function>foreach</function>-Schleife ausgegeben werden, da
3910           für jeden Artikel mehrere Lieferanteninformationen hinterlegt sein
3911           können. Die Variablen dafür lauten:</para>
3912
3913           <variablelist>
3914             <varlistentry>
3915               <term><varname>make</varname></term>
3916
3917               <listitem>
3918                 <para>Lieferant</para>
3919               </listitem>
3920             </varlistentry>
3921
3922             <varlistentry>
3923               <term><varname>model</varname></term>
3924
3925               <listitem>
3926                 <para>Lieferantenartikelnummer</para>
3927               </listitem>
3928             </varlistentry>
3929           </variablelist>
3930         </sect3>
3931
3932         <sect3 id="dokumentenvorlagen-und-variablen.invoice-zahlungen">
3933           <title>Variablen für die einzelnen Zahlungseingänge</title>
3934
3935           <variablelist>
3936             <varlistentry>
3937               <term><varname>payment</varname></term>
3938
3939               <listitem>
3940                 <para>Betrag</para>
3941               </listitem>
3942             </varlistentry>
3943
3944             <varlistentry>
3945               <term><varname>paymentaccount</varname></term>
3946
3947               <listitem>
3948                 <para>Konto</para>
3949               </listitem>
3950             </varlistentry>
3951
3952             <varlistentry>
3953               <term><varname>paymentdate</varname></term>
3954
3955               <listitem>
3956                 <para>Datum</para>
3957               </listitem>
3958             </varlistentry>
3959
3960             <varlistentry>
3961               <term><varname>paymentmemo</varname></term>
3962
3963               <listitem>
3964                 <para>Memo</para>
3965               </listitem>
3966             </varlistentry>
3967
3968             <varlistentry>
3969               <term><varname>paymentsource</varname></term>
3970
3971               <listitem>
3972                 <para>Beleg</para>
3973               </listitem>
3974             </varlistentry>
3975           </variablelist>
3976         </sect3>
3977
3978         <sect3 id="dokumentenvorlagen-und-variablen.benutzerdefinierte-variablen-vc">
3979           <title>Benutzerdefinierte Kunden- und Lieferantenvariablen</title>
3980
3981           <para>Die vom Benutzer definierten Variablen für Kunden und
3982           Lieferanten stehen beim Ausdruck von Einkaufs- und Verkaufsbelegen
3983           ebenfalls zur Verfügung. Ihre Namen setzen sich aus dem Präfix
3984           <varname>vc_cvar_</varname> und dem vom Benutzer festgelegten
3985           Variablennamen zusammen.</para>
3986
3987           <para>Beispiel: Der Benutzer hat eine Variable namens
3988           <varname>number_of_employees</varname> definiert, die die Anzahl der
3989           Mitarbeiter des Unternehmens enthält. Diese Variable steht dann
3990           unter dem Namen <varname>vc_cvar_number_of_employees</varname> zur
3991           Verfügung.</para>
3992         </sect3>
3993       </sect2>
3994
3995       <sect2 id="dokumentenvorlagen-und-variablen.dunning">
3996         <title>Variablen in Mahnungen und Rechnungen über Mahngebühren</title>
3997
3998         <sect3 id="dokumentenvorlagen-und-variablen.dunning-vorlagennamen">
3999           <title>Namen der Vorlagen</title>
4000
4001           <para>Die Namen der Vorlagen werden im System-Menü vom Benutzer
4002           eingegeben. Wird für ein Mahnlevel die Option zur automatischen
4003           Erstellung einer Rechnung über die Mahngebühren und Zinsen
4004           aktiviert, so wird der Name der Vorlage für diese Rechnung aus dem
4005           Vorlagenname für diese Mahnstufe mit dem Zusatz
4006           <constant>_invoice</constant> gebildet. Weiterhin werden die Kürzel
4007           für die ausgewählte Sprache und den ausgewählten Drucker
4008           angehängt.</para>
4009         </sect3>
4010
4011         <sect3 id="dokumentenvorlagen-und-variablen.dunning-allgemein">
4012           <title>Allgemeine Variablen in Mahnungen</title>
4013
4014           <para>Die Variablen des Verkäufers stehen wie gewohnt als
4015           <varname>employee_...</varname> zur Verfügung. Die Adressdaten des
4016           Kunden stehen als Variablen <varname>name</varname>,
4017           <varname>street</varname>, <varname>zipcode</varname>,
4018           <varname>city</varname>, <varname>country</varname>,
4019           <varname>department_1</varname>, <varname>department_2</varname>,
4020           und <varname>email</varname> zur Verfügung.</para>
4021
4022           <para>Weitere Variablen beinhalten:</para>
4023
4024           <variablelist>
4025             <varlistentry>
4026               <term><varname>dunning_date</varname></term>
4027
4028               <listitem>
4029                 <para>Datum der Mahnung</para>
4030               </listitem>
4031             </varlistentry>
4032
4033             <varlistentry>
4034               <term><varname>dunning_duedate</varname></term>
4035
4036               <listitem>
4037                 <para>Fälligkeitsdatum für diese Mahhnung</para>
4038               </listitem>
4039             </varlistentry>
4040
4041             <varlistentry>
4042               <term><varname>dunning_id</varname></term>
4043
4044               <listitem>
4045                 <para>Mahnungsnummer</para>
4046               </listitem>
4047             </varlistentry>
4048
4049             <varlistentry>
4050               <term><varname>fee</varname></term>
4051
4052               <listitem>
4053                 <para>Kummulative Mahngebühren</para>
4054               </listitem>
4055             </varlistentry>
4056
4057             <varlistentry>
4058               <term><varname>interest_rate</varname></term>
4059
4060               <listitem>
4061                 <para>Zinssatz per anno in Prozent</para>
4062               </listitem>
4063             </varlistentry>
4064
4065             <varlistentry>
4066               <term><varname>total_amount</varname></term>
4067
4068               <listitem>
4069                 <para>Gesamter noch zu zahlender Betrag als
4070                 <function>fee</function> + <function>total_interest</function>
4071                 + <function>total_open_amount</function></para>
4072               </listitem>
4073             </varlistentry>
4074
4075             <varlistentry>
4076               <term><varname>total_interest</varname></term>
4077
4078               <listitem>
4079                 <para>Zinsen per anno über alle Rechnungen</para>
4080               </listitem>
4081             </varlistentry>
4082
4083             <varlistentry>
4084               <term><varname>total_open_amount</varname></term>
4085
4086               <listitem>
4087                 <para>Summe über alle offene Beträge der Rechnungen</para>
4088               </listitem>
4089             </varlistentry>
4090           </variablelist>
4091         </sect3>
4092
4093         <sect3 id="dokumentenvorlagen-und-variablen.dunning-details">
4094           <title>Variablen für jede gemahnte Rechnung in einer Mahnung</title>
4095
4096           <variablelist>
4097             <varlistentry>
4098               <term><varname>dn_amount</varname></term>
4099
4100               <listitem>
4101                 <para>Rechnungssumme (brutto)</para>
4102               </listitem>
4103             </varlistentry>
4104
4105             <varlistentry>
4106               <term><varname>dn_duedate</varname></term>
4107
4108               <listitem>
4109                 <para>Originales Fälligkeitsdatum der Rechnung</para>
4110               </listitem>
4111             </varlistentry>
4112
4113             <varlistentry>
4114               <term><varname>dn_dunning_date</varname></term>
4115
4116               <listitem>
4117                 <para>Datum der Mahnung</para>
4118               </listitem>
4119             </varlistentry>
4120
4121             <varlistentry>
4122               <term><varname>dn_dunning_duedate</varname></term>
4123
4124               <listitem>
4125                 <para>Fälligkeitsdatum der Mahnung</para>
4126               </listitem>
4127             </varlistentry>
4128
4129             <varlistentry>
4130               <term><varname>dn_fee</varname></term>
4131
4132               <listitem>
4133                 <para>Kummulative Mahngebühr</para>
4134               </listitem>
4135             </varlistentry>
4136
4137             <varlistentry>
4138               <term><varname>dn_interest</varname></term>
4139
4140               <listitem>
4141                 <para>Zinsen per anno für diese Rechnung</para>
4142               </listitem>
4143             </varlistentry>
4144
4145             <varlistentry>
4146               <term><varname>dn_invnumber</varname></term>
4147
4148               <listitem>
4149                 <para>Rechnungsnummer</para>
4150               </listitem>
4151             </varlistentry>
4152
4153             <varlistentry>
4154               <term><varname>dn_linetotal</varname></term>
4155
4156               <listitem>
4157                 <para>Noch zu zahlender Betrag (ergibt sich aus
4158                 <varname>dn_open_amount</varname> + <varname>dn_fee</varname>
4159                 + <varname>dn_interest</varname>)</para>
4160               </listitem>
4161             </varlistentry>
4162
4163             <varlistentry>
4164               <term><varname>dn_netamount</varname></term>
4165
4166               <listitem>
4167                 <para>Rechnungssumme (netto)</para>
4168               </listitem>
4169             </varlistentry>
4170
4171             <varlistentry>
4172               <term><varname>dn_open_amount</varname></term>
4173
4174               <listitem>
4175                 <para>Offener Rechnungsbetrag</para>
4176               </listitem>
4177             </varlistentry>
4178
4179             <varlistentry>
4180               <term><varname>dn_ordnumber</varname></term>
4181
4182               <listitem>
4183                 <para>Bestellnummer</para>
4184               </listitem>
4185             </varlistentry>
4186
4187             <varlistentry>
4188               <term><varname>dn_transdate</varname></term>
4189
4190               <listitem>
4191                 <para>Rechnungsdatum</para>
4192               </listitem>
4193             </varlistentry>
4194
4195             <varlistentry>
4196               <term><varname>dn_curr</varname></term>
4197
4198               <listitem>
4199                 <para>Währung, in der die Rechnung erstellt wurde. (Die
4200                 Rechnungsbeträge sind aber immer in der Hauptwährung)</para>
4201               </listitem>
4202             </varlistentry>
4203           </variablelist>
4204         </sect3>
4205
4206         <sect3 id="dokumentenvorlagen-und-variablen.dunning-invoice">
4207           <title>Variablen in automatisch erzeugten Rechnungen über
4208           Mahngebühren</title>
4209
4210           <para>Die Variablen des Verkäufers stehen wie gewohnt als
4211           <varname>employee_...</varname> zur Verfügung. Die Adressdaten des
4212           Kunden stehen als Variablen <varname>name</varname>,
4213           <varname>street</varname>, <varname>zipcode</varname>,
4214           <varname>city</varname>, <varname>country</varname>,
4215           <varname>department_1</varname>, <varname>department_2</varname>,
4216           und <varname>email</varname> zur Verfügung.</para>
4217
4218           <para>Weitere Variablen beinhalten:</para>
4219
4220           <variablelist>
4221             <varlistentry>
4222               <term><varname>duedate</varname></term>
4223
4224               <listitem>
4225                 <para>Fälligkeitsdatum der Rechnung</para>
4226               </listitem>
4227             </varlistentry>
4228
4229             <varlistentry>
4230               <term><varname>dunning_id</varname></term>
4231
4232               <listitem>
4233                 <para>Mahnungsnummer</para>
4234               </listitem>
4235             </varlistentry>
4236
4237             <varlistentry>
4238               <term><varname>fee</varname></term>
4239
4240               <listitem>
4241                 <para>Mahngebühren</para>
4242               </listitem>
4243             </varlistentry>
4244
4245             <varlistentry>
4246               <term><varname>interest</varname></term>
4247
4248               <listitem>
4249                 <para>Zinsen</para>
4250               </listitem>
4251             </varlistentry>
4252
4253             <varlistentry>
4254               <term><varname>invamount</varname></term>
4255
4256               <listitem>
4257                 <para>Rechnungssumme (ergibt sich aus <varname>fee</varname> +
4258                 <varname>interest</varname>)</para>
4259               </listitem>
4260             </varlistentry>
4261
4262             <varlistentry>
4263               <term><varname>invdate</varname></term>
4264
4265               <listitem>
4266                 <para>Rechnungsdatum</para>
4267               </listitem>
4268             </varlistentry>
4269
4270             <varlistentry>
4271               <term><varname>invnumber</varname></term>
4272
4273               <listitem>
4274                 <para>Rechnungsnummer</para>
4275               </listitem>
4276             </varlistentry>
4277           </variablelist>
4278         </sect3>
4279       </sect2>
4280
4281       <sect2 id="dokumentenvorlagen-und-variablen.andere-vorlagen">
4282         <title>Variablen in anderen Vorlagen</title>
4283
4284         <sect3>
4285           <title>Einführung</title>
4286
4287           <para>Die Variablen in anderen Vorlagen sind ähnlich wie in der
4288           Rechnung. Allerdings heißen die Variablen, die mit
4289           <varname>inv</varname> beginnen, jetzt anders. Bei den Angeboten
4290           fangen sie mit <varname>quo</varname> für "quotation" an:
4291           <varname>quodate</varname> für Angebotsdatum etc. Bei Bestellungen
4292           wiederum fangen sie mit <varname>ord</varname> für "order" an:
4293           <varname>ordnumber</varname> für Bestellnummer etc.</para>
4294
4295           <para>Manche Variablen sind in anderen Vorlagen hingegen gar nicht
4296           vorhanden wie z.B. die für bereits verbuchte Zahlungseingänge. Dies
4297           sind Variablen, die vom Geschäftsablauf her in der entsprechenden
4298           Vorlage keine Bedeutung haben oder noch nicht belegt sein
4299           können.</para>
4300
4301           <para>Im Folgenden werden nur wichtige Unterschiede zu den Variablen
4302           in Rechnungen aufgeführt.</para>
4303         </sect3>
4304
4305         <sect3 id="dokumentenvorlagen-und-variablen.andere-vorlagen-quotations">
4306           <title>Angebote und Preisanfragen</title>
4307
4308           <variablelist>
4309             <varlistentry>
4310               <term><varname>quonumber</varname></term>
4311
4312               <listitem>
4313                 <para>Angebots- bzw. Anfragenummer</para>
4314               </listitem>
4315             </varlistentry>
4316
4317             <varlistentry>
4318               <term><varname>reqdate</varname></term>
4319
4320               <listitem>
4321                 <para>Gültigkeitsdatum (bei Angeboten) bzw. Lieferdatum (bei
4322                 Preisanfragen)</para>
4323               </listitem>
4324             </varlistentry>
4325
4326             <varlistentry>
4327               <term><varname>transdate</varname></term>
4328
4329               <listitem>
4330                 <para>Angebots- bzw. Anfragedatum</para>
4331               </listitem>
4332             </varlistentry>
4333           </variablelist>
4334         </sect3>
4335
4336         <sect3 id="dokumentenvorlagen-und-variablen.andere-vorlagen-orders">
4337           <title>Auftragsbestätigungen und Lieferantenaufträge</title>
4338
4339           <variablelist>
4340             <varlistentry>
4341               <term><varname>ordnumber</varname></term>
4342
4343               <listitem>
4344                 <para>Auftragsnummer</para>
4345               </listitem>
4346             </varlistentry>
4347
4348             <varlistentry>
4349               <term><varname>reqdate</varname></term>
4350
4351               <listitem>
4352                 <para>Lieferdatum</para>
4353               </listitem>
4354             </varlistentry>
4355
4356             <varlistentry>
4357               <term><varname>transdate</varname></term>
4358
4359               <listitem>
4360                 <para>Auftragsdatum</para>
4361               </listitem>
4362             </varlistentry>
4363           </variablelist>
4364         </sect3>
4365
4366         <sect3 id="dokumentenvorlagen-und-variablen.andere-vorlagen-delivery-orders">
4367           <title>Lieferscheine (Verkauf und Einkauf)</title>
4368
4369           <variablelist>
4370             <varlistentry>
4371               <term><varname>cusordnumber</varname></term>
4372
4373               <listitem>
4374                 <para>Bestellnummer des Kunden (im Verkauf) bzw. Bestellnummer
4375                 des Lieferanten (im Einkauf)</para>
4376               </listitem>
4377             </varlistentry>
4378
4379             <varlistentry>
4380               <term><varname>donumber</varname></term>
4381
4382               <listitem>
4383                 <para>Lieferscheinnummer</para>
4384               </listitem>
4385             </varlistentry>
4386
4387             <varlistentry>
4388               <term><varname>transdate</varname></term>
4389
4390               <listitem>
4391                 <para>Lieferscheindatum</para>
4392               </listitem>
4393             </varlistentry>
4394           </variablelist>
4395
4396           <para>Für jede Position eines Lieferscheines gibt es ein Unterarray
4397           mit den Informationen darüber, von welchem Lager und Lagerplatz aus
4398           die Waren verschickt wurden (Verkaufslieferscheine) bzw. auf welchen
4399           Lagerplatz sie eingelagert wurden. Diese müssen mittels einer
4400           <function>foreach</function>-Schleife ausgegeben werden. Diese
4401           Variablen sind:</para>
4402
4403           <variablelist>
4404             <varlistentry>
4405               <term><varname>si_bin</varname></term>
4406
4407               <listitem>
4408                 <para>Lagerplatz</para>
4409               </listitem>
4410             </varlistentry>
4411
4412             <varlistentry>
4413               <term><varname>si_chargenumber</varname></term>
4414
4415               <listitem>
4416                 <para>Chargennummer</para>
4417               </listitem>
4418             </varlistentry>
4419
4420             <varlistentry>
4421               <term><varname>si_bestbefore</varname></term>
4422
4423               <listitem>
4424                 <para>Mindesthaltbarkeit</para>
4425               </listitem>
4426             </varlistentry>
4427
4428             <varlistentry>
4429               <term><varname>si_number</varname></term>
4430
4431               <listitem>
4432                 <para>Artikelnummer</para>
4433               </listitem>
4434             </varlistentry>
4435
4436             <varlistentry>
4437               <term><varname>si_qty</varname></term>
4438
4439               <listitem>
4440                 <para>Anzahl bzw. Menge</para>
4441               </listitem>
4442             </varlistentry>
4443
4444             <varlistentry>
4445               <term><varname>si_runningnumber</varname></term>
4446
4447               <listitem>
4448                 <para>Positionsnummer (1, 2, 3 etc)</para>
4449               </listitem>
4450             </varlistentry>
4451
4452             <varlistentry>
4453               <term><varname>si_unit</varname></term>
4454
4455               <listitem>
4456                 <para>Einheit</para>
4457               </listitem>
4458             </varlistentry>
4459
4460             <varlistentry>
4461               <term><varname>si_warehouse</varname></term>
4462
4463               <listitem>
4464                 <para>Lager</para>
4465               </listitem>
4466             </varlistentry>
4467           </variablelist>
4468         </sect3>
4469
4470         <sect3 id="dokumentenvorlagen-und-variablen.andere-vorlagen-statement">
4471           <title>Variablen für Sammelrechnung</title>
4472
4473           <variablelist>
4474             <varlistentry>
4475               <term><varname>c0total</varname></term>
4476
4477               <listitem>
4478                 <para>Gesamtbetrag aller Rechnungen mit Fälligkeit &lt; 30
4479                 Tage</para>
4480               </listitem>
4481             </varlistentry>
4482
4483             <varlistentry>
4484               <term><varname>c30total</varname></term>
4485
4486               <listitem>
4487                 <para>Gesamtbetrag aller Rechnungen mit Fälligkeit &gt;= 30
4488                 und &lt; 60 Tage</para>
4489               </listitem>
4490             </varlistentry>
4491
4492             <varlistentry>
4493               <term><varname>c60total</varname></term>
4494
4495               <listitem>
4496                 <para>Gesamtbetrag aller Rechnungen mit Fälligkeit &gt;= 60
4497                 und &lt; 90 Tage</para>
4498               </listitem>
4499             </varlistentry>
4500
4501             <varlistentry>
4502               <term><varname>c90total</varname></term>
4503
4504               <listitem>
4505                 <para>Gesamtbetrag aller Rechnungen mit Fälligkeit &gt;= 90
4506                 Tage</para>
4507               </listitem>
4508             </varlistentry>
4509
4510             <varlistentry>
4511               <term><varname>total</varname></term>
4512
4513               <listitem>
4514                 <para>Gesamtbetrag aller Rechnungen</para>
4515               </listitem>
4516             </varlistentry>
4517           </variablelist>
4518
4519           <para>Variablen für jede Rechnungsposition in Sammelrechnung:</para>
4520
4521           <variablelist>
4522             <varlistentry>
4523               <term><varname>invnumber</varname></term>
4524
4525               <listitem>
4526                 <para>Rechnungsnummer</para>
4527               </listitem>
4528             </varlistentry>
4529
4530             <varlistentry>
4531               <term><varname>invdate</varname></term>
4532
4533               <listitem>
4534                 <para>Rechnungsdatum</para>
4535               </listitem>
4536             </varlistentry>
4537
4538             <varlistentry>
4539               <term><varname>duedate</varname></term>
4540
4541               <listitem>
4542                 <para>Fälligkeitsdatum</para>
4543               </listitem>
4544             </varlistentry>
4545
4546             <varlistentry>
4547               <term><varname>amount</varname></term>
4548
4549               <listitem>
4550                 <para>Summe der Rechnung</para>
4551               </listitem>
4552             </varlistentry>
4553
4554             <varlistentry>
4555               <term><varname>open</varname></term>
4556
4557               <listitem>
4558                 <para>Noch offener Betrag der Rechnung</para>
4559               </listitem>
4560             </varlistentry>
4561
4562             <varlistentry>
4563               <term><varname>c0</varname></term>
4564
4565               <listitem>
4566                 <para>Noch offener Rechnungsbetrag mit Fälligkeit &lt; 30
4567                 Tage</para>
4568               </listitem>
4569             </varlistentry>
4570
4571             <varlistentry>
4572               <term><varname>c30</varname></term>
4573
4574               <listitem>
4575                 <para>Noch offener Rechnungsbetrag mit Fälligkeit &gt;= 30 und
4576                 &lt; 60 Tage</para>
4577               </listitem>
4578             </varlistentry>
4579
4580             <varlistentry>
4581               <term><varname>c60</varname></term>
4582
4583               <listitem>
4584                 <para>Noch offener Rechnungsbetrag mit Fälligkeit &gt;= 60 und
4585                 &lt; 90 Tage</para>
4586               </listitem>
4587             </varlistentry>
4588
4589             <varlistentry>
4590               <term><varname>c90</varname></term>
4591
4592               <listitem>
4593                 <para>Noch offener Rechnungsbetrag mit Fälligkeit &gt;= 90
4594                 Tage</para>
4595               </listitem>
4596             </varlistentry>
4597           </variablelist>
4598         </sect3>
4599       </sect2>
4600
4601       <sect2 id="dokumentenvorlagen-und-variablen.bloecke">
4602         <title>Blöcke, bedingte Anweisungen und Schleifen</title>
4603
4604         <sect3 id="dokumentenvorlagen-und-variablen.bloecke.einfuehrung">
4605           <title>Einfürhung</title>
4606
4607           <para>Der Parser kennt neben den Variablen einige weitere
4608           Konstrukte, die gesondert behandelt werden. Diese sind wie
4609           Variablennamen in spezieller Weise markiert:
4610           <command>&lt;%anweisung%&gt; ... &lt;%end%&gt;</command></para>
4611
4612           <para>Anmerkung zum <command>&lt;%end%&gt;</command>: Der besseren
4613           Verständlichkeit halber kann man nach dem <command>end</command>
4614           noch beliebig weitere Wörter schreiben, um so zu markieren, welche
4615           Anweisung (z.B. <command>if</command> oder
4616           <command>foreach</command>) damit abgeschlossen wird.</para>
4617
4618           <para>Beispiel: Lautet der Beginn eines Blockes z.B.
4619           <command>&lt;%if type == "sales_quotation"%&gt;</command>, so könnte
4620           er mit <command>&lt;%end%&gt;</command> genauso abgeschlossen werden
4621           wie mit <command>&lt;%end if%&gt;</command> oder auch
4622           <command>&lt;%end type == "sales_quotation"%&gt;</command>.</para>
4623         </sect3>
4624
4625         <sect3 id="dokumentenvorlagen-und-variablen.bloecke.if">
4626           <title>Der if-Block</title>
4627
4628           <programlisting>&lt;%if variablenname%&gt;
4629 ...
4630 &lt;%end%&gt;</programlisting>
4631
4632           <para>Eine normale "if-then"-Bedingung. Die Zeilen zwischen dem "if"
4633           und dem "end" werden nur ausgegeben, wenn die Variable
4634           <varname>variablenname</varname> gesetzt und ungleich 0 ist.</para>
4635
4636           <para>Handelt es sich bei der benannten Variable um ein Array, also um einen Variablennamen, über den man mit
4637           <command>&lt;%foreach variablenname%&gt;</command> iteriert, so wird mit diesem Konstrukt darauf getestet, ob das Array Elemente
4638           enthält. Somit würde im folgenden Beispiel nur dann eine Liste von Zahlungseingängen samt ihrer Überschrift "Zahlungseingänge"
4639           ausgegeben, wenn tatsächlich welche getätigt wurden:</para>
4640
4641           <programlisting>&lt;%if payment%&gt;
4642 Zahlungseingänge:
4643  &lt;%foreach payment%&gt;
4644    Am &lt;%paymentdate%&gt;: &lt;%payment%&gt; €
4645  &lt;%end foreach%&gt;
4646 &lt;%end if%&gt;</programlisting>
4647
4648           <para>Die Bedingung kann auch negiert werden, indem das Wort
4649           <function>not</function> nach dem <filename>if</filename> verwendet
4650           wird. Beispiel:</para>
4651
4652           <programlisting>&lt;%if not cp_greeting%&gt;
4653 ...
4654 &lt;%end%&gt;</programlisting>
4655
4656           <para>Zusätzlich zu dem einfachen Test, ob eine Variable gesetzt ist
4657           oder nicht, bietet dieser Block auch die Möglichkeit, den Inhalt
4658           einer Variablen mit einer festen Zeichenkette oder einer anderen
4659           Variablen zu vergleichen. Ob der Vergleich mit einer Zeichenkette
4660           oder einer anderen Variablen vorgenommen wird, hängt davon ab, ob
4661           die rechte Seite des Vergleichsoperators in Anführungszeichen
4662           gesetzt wird (Vergleich mit Zeichenkette) oder nicht (Vergleich mit
4663           anderer Variablen). Zwei Beispiele, die beide Vergleiche
4664           zeigen:</para>
4665
4666           <programlisting>&lt;%if var1 == "Wert"%&gt;</programlisting>
4667
4668           <para>Testet die Variable <varname>var1</varname> auf
4669           übereinstimmung mit der Zeichenkette <constant>Wert</constant>.
4670           Mittels <function>!=</function> anstelle von <function>==</function>
4671           würde auf Ungleichheit getestet.</para>
4672
4673           <programlisting>&lt;%if var1 == var2%&gt;</programlisting>
4674
4675           <para>Testet die Variable <varname>var1</varname> auf
4676           übereinstimmung mit der Variablen <varname>var2</varname>. Mittel
4677           <function>!=</function> anstelle von <function>==</function> würde
4678           auf Ungleichheit getestet.</para>
4679
4680           <para>Erfahrere Benutzer können neben der Tests auf (Un-)Gleichheit
4681           auch Tests auf übereinstimmung mit regulären Ausdrücken ohne
4682           Berücksichtung der Groß- und Kleinschreibung durchführen. Dazu dient
4683           dieselbe Syntax wie oben nur mit <function>=~</function> und
4684           <function>!~</function> als Vergleichsoperatoren.</para>
4685
4686           <para>Beispiel für einen Test, ob die Variable
4687           <varname>intnotes</varname> (interne Bemerkungen) das Wort
4688           <constant>schwierig</constant> enthält:</para>
4689
4690           <programlisting>&lt;%if intnotes =~ "schwierig"%&gt;</programlisting>
4691         </sect3>
4692
4693         <sect3 id="dokumentenvorlagen-und-variablen.bloecke.foreach">
4694           <title>Der foreach-Block</title>
4695
4696           <programlisting>&lt;%foreach variablenname%&gt;
4697 ...
4698 &lt;%end%&gt;</programlisting>
4699
4700           <para>Fügt die Zeilen zwischen den beiden Anweisungen so oft ein,
4701           wie das Perl-Array der Variablen <varname>variablenname</varname>
4702           Elemente enthät. Dieses Konstrukt wird zur Ausgabe der einzelnen
4703           Posten einer Rechnung / eines Angebots sowie zur Ausgabe der Steuern
4704           benutzt. In jedem Durchlauf werden die <link
4705           linkend="dokumentenvorlagen-und-variablen.invoice-posten">zeilenbezogenen
4706           Variablen</link> jeweils auf den Wert für die aktuelle Position
4707           gesetzt.</para>
4708
4709           <para>Die Syntax sieht normalerweise wie folgt aus:</para>
4710
4711           <programlisting>&lt;%foreach number%&gt;
4712 Position: &lt;%runningnumber%&gt;
4713 Anzahl: &lt;%qty%&gt;
4714 Artikelnummer: &lt;%number%&gt;
4715 Beschreibung: &lt;%description%&gt;
4716 ...
4717 &lt;%end%&gt;</programlisting>
4718
4719           <para>Besonderheit in OpenDocument-Vorlagen: Tritt ein
4720           <function>&lt;%foreach%&gt;</function>-Block innerhalb einer
4721           Tabellenzelle auf, so wird die komplette Tabellenzeile so oft
4722           wiederholt wie notwendig. Tritt er außerhalb auf, so wird nur der
4723           Inhalt zwischen <function>&lt;%foreach%&gt;</function> und
4724           <function>&lt;%end%&gt;</function> wiederholt, nicht aber die
4725           komplette Zeile, in der er steht.</para>
4726         </sect3>
4727       </sect2>
4728
4729       <sect2 id="dokumentenvorlagen-und-variablen.markup">
4730         <title>Markup-Code zur Textformatierung innerhalb von
4731         Formularen</title>
4732
4733         <para>Wenn der Benutzer innhalb von Formularen in kivitendo Text
4734         anders formatiert haben möchte, so ist dies begrenzt möglich.
4735         kivitendo unterstützt die Textformatierung mit HTML-ähnlichen Tags.
4736         Der Benutzer kann z.B. bei der Artikelbeschreibung auf einer Rechnung
4737         Teile des Texts zwischen Start- und Endtags setzen. Dieser Teil wird
4738         dann automatisch in Anweisungen für das ausgewählte Vorlagenformat
4739         (HTML oder PDF über LaTeX) umgesetzt.</para>
4740
4741         <para>Die unterstützen Formatierungen sind:</para>
4742
4743         <variablelist>
4744           <varlistentry>
4745             <term>&lt;b&gt;Text&lt;/b&gt;</term>
4746
4747             <listitem>
4748               <para>Text wird in Fettdruck gesetzt.</para>
4749             </listitem>
4750           </varlistentry>
4751
4752           <varlistentry>
4753             <term>&lt;i&gt;Text&lt;/i&gt;</term>
4754
4755             <listitem>
4756               <para>Text wird kursiv gesetzt.</para>
4757             </listitem>
4758           </varlistentry>
4759
4760           <varlistentry>
4761             <term>&lt;u&gt;Text&lt;/u&gt;</term>
4762
4763             <listitem>
4764               <para>Text wird unterstrichen.</para>
4765             </listitem>
4766           </varlistentry>
4767
4768           <varlistentry>
4769             <term>&lt;s&gt;Text&lt;/s&gt;</term>
4770
4771             <listitem>
4772               <para>Text wird durchgestrichen. Diese Formatierung ist nicht
4773               bei der Ausgabe als PDF über LaTeX verfügbar.</para>
4774             </listitem>
4775           </varlistentry>
4776
4777           <varlistentry>
4778             <term>&lt;bullet&gt;</term>
4779
4780             <listitem>
4781               <para>Erzeugt einen ausgefüllten Kreis für Aufzählungen (siehe
4782               unten).</para>
4783             </listitem>
4784           </varlistentry>
4785         </variablelist>
4786
4787         <para>Der Befehl <command>&lt;bullet&gt;</command> funktioniert
4788         momentan auch nur in Latex-Vorlagen.</para>
4789       </sect2>
4790     </sect1>
4791
4792     <sect1 id="excel-templates">
4793       <title>Excel-Vorlagen</title>
4794
4795       <sect2 id="excel-templates.summary">
4796         <title>Zusammenfassung</title>
4797
4798         <para>Dieses Dokument beschreibt den Mechanismus, mit dem
4799         Exceltemplates abgearbeitet werden, und die Einschränkungen, die damit
4800         einhergehen.</para>
4801       </sect2>
4802
4803       <sect2 id="excel-templates.usage">
4804         <title>Bedienung</title>
4805
4806         <para>Der Excel Mechanismus muss in der Konfigurationsdatei aktiviert
4807         werden. Die Konfigurationsoption heißt <varname>excel_templates =
4808         1</varname> im Abschnitt <varname>[print_templates]</varname>.</para>
4809
4810         <para>Eine Excelvorlage kann dann unter dem Namen einer beliebigen
4811         anderen Vorlage mit der Endung <filename>.xls</filename> gespeichert
4812         werden. In den normalen Verkaufsmasken taucht nun
4813         <constant>Excel</constant> als auswählbares Format auf und kann von da
4814         an wie LaTeX- oder OpenOffice-Vorlagen benutzt werden.</para>
4815
4816         <para>Der Sonderfall der Angebote aus der Kundenmaske ist ebenfalls
4817         eine Angebotsvorlage und wird unter dem internen Namen der Angebote
4818         <filename>sales_quotation.xls</filename> gespeichert.</para>
4819       </sect2>
4820
4821       <sect2 id="excel-templates.syntax">
4822         <title>Variablensyntax</title>
4823
4824         <para>Einfache Syntax:
4825         <command>&lt;&lt;varname&gt;&gt;</command></para>
4826
4827         <para>Dabei sind <constant>&lt;&lt;</constant> und
4828         <constant>&gt;&gt;</constant> die Delimiter. Da Excel auf festen
4829         Breiten besteht, kann der Tag künstlich verlängert werden, indem
4830         weitere <constant>&lt;</constant> oder <constant>&gt;</constant>
4831         eingefügt werden. Der Tag muss nicht symmetrisch sein.
4832         Beispiel:</para>
4833
4834         <programlisting>&lt;&lt;&lt;&lt;&lt;varname&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;</programlisting>
4835
4836         <para>Um die Limitierung der festen Breite zu reduzieren, können
4837         weitere Variablen in einem Block interpoliert werden. Whitespace wird
4838         dazwishen dann erhalten. Beispiel:</para>
4839
4840         <programlisting>&lt;&lt;&lt;&lt;&lt;varname1 varname2   varname3&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;</programlisting>
4841
4842         <para>Die Variablen werden interpoliert, und linksbündig mit
4843         Leerzeichen auf die gewünschte Länge aufgefüllt. Ist der String zu
4844         lang, werden überzählige Zeichen abgeschnitten.</para>
4845
4846         <para>Es ist ausserdem möglich, Daten rechtsbündig darzustellen, wenn
4847         der Block mit einem Leerzeichen anfängt. Beispiel:</para>
4848
4849         <programlisting>&lt;&lt;&lt;&lt;&lt;&lt;            varname&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;&gt;</programlisting>
4850
4851         <para>Dies würde rechtsbündig triggern. Wenn bei rechtsbündiger
4852         Ausrichtung Text abgeschnitten werden muss, wird er vom linken Ende
4853         entfernt.</para>
4854       </sect2>
4855
4856       <sect2 id="excel-templates.limitations">
4857         <title>Einschränkungen</title>
4858
4859         <para>Das Excelformat bis 2002 ist ein binäres Format, und kann nicht
4860         mit vertretbarem Aufwand editiert werden. Der Templatemechanismus
4861         beschränkt sich daher darauf, Textstellen exakt durch einen anderen
4862         Text zu ersetzen.</para>
4863
4864         <para>Aus dem gleichen Grund sind die Kontrolllstrukturen
4865         <command>&lt;%if%&gt;</command> und
4866         <command>&lt;%foreach%&gt;</command> nicht vorhanden. Der Delimiter
4867         <constant>&lt;% %&gt;</constant> kommt in den Headerinformationen
4868         evtl. vor. Deshalb wurde auf den sichereren Delimiter
4869         <constant>&lt;&lt;</constant> und <constant>&gt;&gt;</constant>
4870         gewechselt.</para>
4871       </sect2>
4872     </sect1>
4873     <sect1 id="features.warehouse">
4874     <title>Mandantenkonfiguration Lager</title>
4875         Die Lagerverwaltung in kivitendo funktioniert standardmässig wie folgt:
4876         Wird ein Lager mit einem Lagerplatz angelegt, so gibt es die Möglichkeit hier über den
4877         Menüpunkt Lager entsprechende Warenbewegungen durchzuführen. Ferner kann
4878         jede Position eines Lieferscheins ein-, bzw. ausgelagert werden (Einkauf-, bzw. Verkauf).
4879         Es können beliebig viele Lager mit beliebig vielen Lagerplätzen abgebildet werden.
4880         Die Lagerbewegungen über einen Lieferschein erfolgt durch Anklicken jeder Einzelposition und
4881         das Auswählen dieser Position zu einem Lager mit Lagerplatz.
4882         Dieses Verfahren lässt sich schrittweise vereinfachen, je nachdem wie die Einstellungen in
4883         der Mandatenkonfiguration gesetzt werden.
4884        <itemizedlist>
4885           <listitem>
4886             <para><option>Auslagern über Standardlagerplatz</option> Hier wird ein zusätzlicher Knopf (Auslagern über Standard-Lagerplatz)
4887             in dem Lieferschein-Beleg hinzugefügt, der dann alle Lagerbewegungen über den Standardlagerplatz (konfigurierbar pro Ware) durchführt.
4888             </para>
4889           </listitem>
4890           <listitem>
4891             <para><option>Auslagern ohne Bestandsprüfung</option>Das obige Auslagern schlägt fehl, wenn die entsprechende Menge für
4892             die Lagerbewegung nicht vorhanden ist, möchte man dies auch ignorieren und ggf. dann nachpflegen, so kann man eine Negativ-Warenmenge mit dieser Option
4893             erlauben. Hierfür muss ein entsprechender Lagerplatz (Fehlbestand, o.ä.) konfiguriert sein.</para>
4894           </listitem>
4895        </itemizedlist>
4896         Zusätzliche Funktionshinweise:
4897          <itemizedlist>
4898           <listitem><para><option>Standard-Lagerplatz</option>Ist dieser konfiguriert, wird dies auch als Standard-Voreinstellung bei der Neuerfassung von
4899           Stammdaten-> Waren / Dienstleistung / Erzeugnis verwendet.
4900           </para>
4901           </listitem>
4902           <listitem><para><option>Standard-Lagerplatz verwenden, falls keiner in Stammdaten definiert</option>Wird beim 'Auslagern über Standardlagerplatz'
4903           keine Standardlagerplatz zu der Ware gefunden, so wird mit dieser Option einfach der Standardlagerplatz verwendet.
4904           </para>
4905           </listitem>
4906        </itemizedlist>
4907     </sect1>
4908   </chapter>
4909
4910   <chapter>
4911     <title>Entwicklerdokumentation</title>
4912
4913     <sect1 id="devel.globals" xreflabel="Globale Variablen">
4914       <title>Globale Variablen</title>
4915
4916       <sect2>
4917         <title>Wie sehen globale Variablen in Perl aus?</title>
4918
4919         <para>Globale Variablen liegen in einem speziellen namespace namens
4920         "main", der von überall erreichbar ist. Darüber hinaus sind bareword
4921         globs global und die meisten speziellen Variablen sind...
4922         speziell.</para>
4923
4924         <para>Daraus ergeben sich folgende Formen:</para>
4925
4926         <variablelist>
4927           <varlistentry>
4928             <term><literal>$main::form</literal></term>
4929
4930             <listitem>
4931               <para>expliziter Namespace "main"</para>
4932             </listitem>
4933           </varlistentry>
4934
4935           <varlistentry>
4936             <term><literal>$::form</literal></term>
4937
4938             <listitem>
4939               <para>impliziter Namespace "main"</para>
4940             </listitem>
4941           </varlistentry>
4942
4943           <varlistentry>
4944             <term><literal>open FILE, "file.txt"</literal></term>
4945
4946             <listitem>
4947               <para><varname>FILE</varname> ist global</para>
4948             </listitem>
4949           </varlistentry>
4950
4951           <varlistentry>
4952             <term><literal>$_</literal></term>
4953
4954             <listitem>
4955               <para>speziell</para>
4956             </listitem>
4957           </varlistentry>
4958         </variablelist>
4959
4960         <para>Im Gegensatz zu <productname>PHP</productname> gibt es kein
4961         Schlüsselwort wie "<function>global</function>", mit dem man
4962         importieren kann. <function>my</function>, <function>our</function>
4963         und <function>local</function> machen was anderes.</para>
4964
4965         <variablelist>
4966           <varlistentry>
4967             <term><literal>my $form</literal></term>
4968
4969             <listitem>
4970               <para>lexikalische Variable, gültig bis zum Ende des
4971               Scopes</para>
4972             </listitem>
4973           </varlistentry>
4974
4975           <varlistentry>
4976             <term><literal>our $form</literal></term>
4977
4978             <listitem>
4979               <para><varname>$form</varname> referenziert ab hier
4980               <varname>$PACKAGE::form</varname>.</para>
4981             </listitem>
4982           </varlistentry>
4983
4984           <varlistentry>
4985             <term><literal>local $form</literal></term>
4986
4987             <listitem>
4988               <para>Alle Änderungen an <varname>$form</varname> werden am Ende
4989               des scopes zurückgesetzt</para>
4990             </listitem>
4991           </varlistentry>
4992         </variablelist>
4993       </sect2>
4994
4995       <sect2>
4996         <title>Warum sind globale Variablen ein Problem?</title>
4997
4998         <para>Das erste Problem ist <productname>FCGI</productname>.</para>
4999
5000         <para><productname>SQL-Ledger</productname> hat fast alles im globalen
5001         namespace abgelegt, und erwartet, dass es da auch wiederzufinden ist.
5002         Unter <productname>FCGI</productname> müssen diese Sachen aber wieder
5003         aufgeräumt werden, damit sie nicht in den nächsten Request kommen.
5004         Einige Sachen wiederum sollen nicht gelöscht werden, wie zum Beispiel
5005         Datenbankverbindungen, weil die sehr lange zum Initialisieren
5006         brauchen.</para>
5007
5008         <para>Das zweite Problem ist <function>strict</function>. Unter
5009         <function>strict</function> werden alle Variablen die nicht explizit
5010         mit <function>Package</function>, <function>my</function> oder
5011         <function>our</function> angegeben werden als Tippfehler angemarkert,
5012         dies hat, seit der Einführung, u.a. schon so manche langwierige
5013         Bug-Suche verkürzt. Da globale Variablen aber implizit mit Package
5014         angegeben werden, werden die nicht geprüft, und somit kann sich
5015         schnell ein Tippfehler einschleichen.</para>
5016       </sect2>
5017
5018       <sect2>
5019         <title>Kanonische globale Variablen</title>
5020
5021         <para>Um dieses Problem im Griff zu halten gibt es einige wenige
5022         globale Variablen, die kanonisch sind, d.h. sie haben bestimmte
5023         vorgegebenen Eigenschaften, und alles andere sollte anderweitig
5024         umhergereicht werden.</para>
5025
5026         <para>Diese Variablen sind im Moment die folgenden neun:</para>
5027
5028         <itemizedlist>
5029           <listitem>
5030             <para><varname>$::form</varname></para>
5031           </listitem>
5032
5033           <listitem>
5034             <para><varname>%::myconfig</varname></para>
5035           </listitem>
5036
5037           <listitem>
5038             <para><varname>$::locale</varname></para>
5039           </listitem>
5040
5041           <listitem>
5042             <para><varname>$::lxdebug</varname></para>
5043           </listitem>
5044
5045           <listitem>
5046             <para><varname>$::auth</varname></para>
5047           </listitem>
5048
5049           <listitem>
5050             <para><varname>$::lx_office_conf</varname></para>
5051           </listitem>
5052
5053           <listitem>
5054             <para><varname>$::instance_conf</varname></para>
5055           </listitem>
5056
5057           <listitem>
5058             <para><varname>$::dispatcher</varname></para>
5059           </listitem>
5060
5061           <listitem>
5062             <para><varname>$::request</varname></para>
5063           </listitem>
5064         </itemizedlist>
5065
5066         <para>Damit diese nicht erneut als Müllhalde missbraucht werden, im
5067         Folgenden eine kurze Erläuterung der bestimmten vorgegebenen
5068         Eigenschaften (Konventionen):</para>
5069
5070         <sect3>
5071           <title>$::form</title>
5072
5073           <itemizedlist>
5074             <listitem>
5075               <para>Ist ein Objekt der Klasse
5076               "<classname>Form</classname>"</para>
5077             </listitem>
5078
5079             <listitem>
5080               <para>Wird nach jedem Request gelöscht</para>
5081             </listitem>
5082
5083             <listitem>
5084               <para>Muss auch in Tests und Konsolenscripts vorhanden
5085               sein.</para>
5086             </listitem>
5087
5088             <listitem>
5089               <para>Enthält am Anfang eines Requests die Requestparameter vom
5090               User</para>
5091             </listitem>
5092
5093             <listitem>
5094               <para>Kann zwar intern über Requestgrenzen ein Datenbankhandle
5095               cachen, das wird aber momentan absichtlich zerstört</para>
5096             </listitem>
5097           </itemizedlist>
5098
5099           <para><varname>$::form</varname> wurde unter <productname>SQL
5100           Ledger</productname> als Gottobjekt für alles misbraucht. Sämtliche
5101           alten Funktionen unter SL/ mutieren <varname>$::form</varname>, das
5102           heißt, alles was einem lieb ist (alle Variablen die einem ans Herz
5103           gewachsen sind), sollte man vor einem Aufruf (!) von zum Beispiel
5104           <function>IS-&gt;retrieve_customer()</function> in Sicherheit
5105           bringen.</para>
5106
5107           <para>Z.B. das vom Benutzer eingestellte Zahlenformat, bevor man
5108           Berechnung in einem bestimmten Format durchführt (SL/Form.pm Zeile
5109           3552, Stand version 2.7beta), um dies hinterher wieder auf den
5110           richtigen Wert zu setzen:</para>
5111
5112           <programlisting>  my $saved_numberformat    = $::myconfig{numberformat};
5113   $::myconfig{numberformat} = $numberformat;
5114   # (...) div Berechnungen
5115   $::myconfig{numberformat} = $saved_numberformat;</programlisting>
5116
5117           <para>Das Objekt der Klasse Form hat leider im Moment noch viele
5118           zentrale Funktionen die vom internen Zustand abhängen, deshalb bitte
5119           nie einfach zerstören oder überschreiben (zumindestens nicht kurz
5120           vor einem Release oder in Absprache über bspw. die devel-Liste ;-).
5121           Es geht ziemlich sicher etwas kaputt.</para>
5122
5123           <para><varname>$::form</varname> ist gleichzeitig der Standard Scope
5124           in den <productname>Template::Toolkit</productname> Templates
5125           außerhalb der Controller: der Ausdruck <function>[% var
5126           %]</function> greift auf <varname>$::form-&gt;{var}</varname> zu.
5127           Unter Controllern ist der Standard Scope anders, da lautet der
5128           Zugriff <function>[% FORM.var %]</function>. In Druckvorlagen sind
5129           normale Variablen ebenfall im <varname>$::form</varname> Scope, d.h.
5130           <function>&lt;%var%&gt;</function> zeigt auf
5131           <varname>$::form-&gt;{var}</varname>. Nochmal von der anderen Seite
5132           erläutert, innerhalb von (Web-)Templates sieht man häufiger solche
5133           Konstrukte:</para>
5134
5135           <programlisting>[%- IF business %]
5136 # (... Zeig die Auswahlliste Kunden-/Lieferantentyp an)
5137 [%- END %]</programlisting>
5138
5139           <para>Entweder wird hier dann $::form-&gt;{business} ausgewertet
5140           oder aber der Funktion
5141           <function>$form-&gt;parse_html_template</function> wird explizit
5142           noch ein zusätzlicher Hash übergeben, der dann auch in den
5143           (Web-)Templates zu Verfügung steht, bspw. so:</para>
5144
5145           <programlisting>$form-&gt;parse_html_template("is/form_header", \%TMPL_VAR);</programlisting>
5146
5147           <para>Innerhalb von Schleifen wird
5148           <varname>$::form-&gt;{TEMPLATE_ARRAYS}{var}[$index]</varname>
5149           bevorzugt, wenn vorhanden. Ein Beispiel findet sich in SL/DO.pm,
5150           welches über alle Positionen eines Lieferscheins in Schleife
5151           läuft:</para>
5152
5153           <programlisting>for $i (1 .. $form-&gt;{rowcount}) {
5154   # ...
5155   push @{ $form-&gt;{TEMPLATE_ARRAYS}{runningnumber} },   $position;
5156   push @{ $form-&gt;{TEMPLATE_ARRAYS}{number} },          $form-&gt;{"partnumber_$i"};
5157   push @{ $form-&gt;{TEMPLATE_ARRAYS}{description} },     $form-&gt;{"description_$i"};
5158   # ...
5159 }</programlisting>
5160         </sect3>
5161
5162         <sect3>
5163           <title>%::myconfig</title>
5164
5165           <itemizedlist>
5166             <listitem>
5167               <para>Das einzige Hash unter den globalen Variablen</para>
5168             </listitem>
5169
5170             <listitem>
5171               <para>Wird spätestens benötigt wenn auf die Datenbank
5172               zugegriffen wird</para>
5173             </listitem>
5174
5175             <listitem>
5176               <para>Wird bei jedem Request neu erstellt.</para>
5177             </listitem>
5178
5179             <listitem>
5180               <para>Enthält die Userdaten des aktuellen Logins</para>
5181             </listitem>
5182
5183             <listitem>
5184               <para>Sollte nicht ohne Filterung irgendwo gedumpt werden oder
5185               extern serialisiert werden, weil da auch der Datenbankzugriff
5186               für diesen user drinsteht.</para>
5187             </listitem>
5188
5189             <listitem>
5190               <para>Enthält unter anderem Listenbegrenzung vclimit,
5191               Datumsformat dateformat und Nummernformat numberformat</para>
5192             </listitem>
5193
5194             <listitem>
5195               <para>Enthält Datenbankzugriffinformationen</para>
5196             </listitem>
5197           </itemizedlist>
5198
5199           <para><varname>%::myconfig</varname> ist im Moment der Ersatz für
5200           ein Userobjekt. Die meisten Funktionen, die etwas anhand des
5201           aktuellen Users entscheiden müssen, befragen
5202           <varname>%::myconfig</varname>. Innerhalb der Anwendungen sind dies
5203           überwiegend die Daten, die sich unter <guimenu>Programm</guimenu>
5204           -&gt; <guimenuitem>Einstellungen</guimenuitem> befinden, bzw. die
5205           Informationen über den Benutzer die über die
5206           Administrator-Schnittstelle eingegeben wurden.</para>
5207         </sect3>
5208
5209         <sect3>
5210           <title>$::locale</title>
5211
5212           <itemizedlist>
5213             <listitem>
5214               <para>Objekt der Klasse "Locale"</para>
5215             </listitem>
5216
5217             <listitem>
5218               <para>Wird pro Request erstellt</para>
5219             </listitem>
5220
5221             <listitem>
5222               <para>Muss auch für Tests und Scripte immer verfügbar
5223               sein.</para>
5224             </listitem>
5225
5226             <listitem>
5227               <para>Cached intern über Requestgrenzen hinweg benutzte
5228               Locales</para>
5229             </listitem>
5230           </itemizedlist>
5231
5232           <para>Lokalisierung für den aktuellen User. Alle Übersetzungen,
5233           Zahlen- und Datumsformatierungen laufen über dieses Objekt.</para>
5234         </sect3>
5235
5236         <sect3>
5237           <title>$::lxdebug</title>
5238
5239           <itemizedlist>
5240             <listitem>
5241               <para>Objekt der Klasse "LXDebug"</para>
5242             </listitem>
5243
5244             <listitem>
5245               <para>Wird global gecached</para>
5246             </listitem>
5247
5248             <listitem>
5249               <para>Muss immer verfügbar sein, in nahezu allen
5250               Funktionen</para>
5251             </listitem>
5252           </itemizedlist>
5253
5254           <para><varname>$::lxdebug</varname> stellt Debuggingfunktionen
5255           bereit, wie "<function>enter_sub</function>" und
5256           "<function>leave_sub</function>", mit denen in den alten Modulen ein
5257           brauchbares Tracing gebaut ist, "<function>log_time</function>", mit
5258           der man die Wallclockzeit seit Requeststart loggen kann, sowie
5259           "<function>message</function>" und "<function>dump</function>" mit
5260           denen man flott Informationen ins Log (tmp/kivitendo-debug.log)
5261           packen kann.</para>
5262
5263           <para>Beispielsweise so:</para>
5264
5265           <programlisting>$main::lxdebug-&gt;message(0, 'Meine Konfig:' . Dumper (%::myconfig));
5266 $main::lxdebug-&gt;message(0, 'Wer bin ich? Kunde oder Lieferant:' . $form-&gt;{vc});</programlisting>
5267         </sect3>
5268
5269         <sect3>
5270           <title>$::auth</title>
5271
5272           <itemizedlist>
5273             <listitem>
5274               <para>Objekt der Klasse "SL::Auth"</para>
5275             </listitem>
5276
5277             <listitem>
5278               <para>Wird global gecached</para>
5279             </listitem>
5280
5281             <listitem>
5282               <para>Hat eine permanente DB Verbindung zur Authdatenbank</para>
5283             </listitem>
5284
5285             <listitem>
5286               <para>Wird nach jedem Request resettet.</para>
5287             </listitem>
5288           </itemizedlist>
5289
5290           <para><varname>$::auth</varname> stellt Funktionen bereit um die
5291           Rechte des aktuellen Users abzufragen. Obwohl diese Informationen
5292           vom aktuellen User abhängen wird das Objekt aus
5293           Geschwindigkeitsgründen nur einmal angelegt und dann nach jedem
5294           Request kurz resettet.</para>
5295
5296           <para>Dieses Objekt kapselt auch den gerade aktiven Mandanten. Dessen Einstellungen können über
5297           <literal>$::auth-&gt;client</literal> abgefragt werden; Rückgabewert ist ein Hash mit den Werten aus der Tabelle
5298           <literal>auth.clients</literal>.</para>
5299         </sect3>
5300
5301         <sect3>
5302           <title>$::lx_office_conf</title>
5303
5304           <itemizedlist>
5305             <listitem>
5306               <para>Objekt der Klasse
5307               "<classname>SL::LxOfficeConf</classname>"</para>
5308             </listitem>
5309
5310             <listitem>
5311               <para>Global gecached</para>
5312             </listitem>
5313
5314             <listitem>
5315               <para>Repräsentation der
5316               <filename>config/kivitendo.conf[.default]</filename>-Dateien</para>
5317             </listitem>
5318           </itemizedlist>
5319
5320           <para>Globale Konfiguration. Configdateien werden zum Start gelesen
5321           und danach nicht mehr angefasst. Es ist derzeit nicht geplant, dass
5322           das Programm die Konfiguration ändern kann oder sollte.</para>
5323
5324           <para>Beispielsweise ist über den Konfigurationseintrag [debug] die
5325           Debug- und Trace-Log-Datei wie folgt konfiguriert und
5326           verfügbar:</para>
5327
5328           <programlisting>[debug]
5329 file_name = /tmp/kivitendo-debug.log</programlisting>
5330
5331           <para>ist der Key <varname>file</varname> im Programm als
5332           <varname>$::lx_office_conf-&gt;{debug}{file}</varname>
5333           erreichbar.</para>
5334
5335           <warning>
5336             <para>Zugriff auf die Konfiguration erfolgt im Moment über
5337             Hashkeys, sind also nicht gegen Tippfehler abgesichert.</para>
5338           </warning>
5339         </sect3>
5340
5341         <sect3>
5342           <title>$::instance_conf</title>
5343
5344           <itemizedlist>
5345             <listitem>
5346               <para>Objekt der Klasse
5347               "<classname>SL::InstanceConfiguration</classname>"</para>
5348             </listitem>
5349
5350             <listitem>
5351               <para>wird pro Request neu erstellt</para>
5352             </listitem>
5353           </itemizedlist>
5354
5355           <para>Funktioniert wie <varname>$::lx_office_conf</varname>,
5356           speichert aber Daten die von der Instanz abhängig sind. Eine Instanz
5357           ist hier eine Mandantendatenbank. Beispielsweise überprüft
5358           <programlisting>$::instance_conf-&gt;get_inventory_system eq 'perpetual'</programlisting>
5359           ob die berüchtigte Bestandsmethode zur Anwendung kommt.</para>
5360         </sect3>
5361
5362         <sect3>
5363           <title>$::dispatcher</title>
5364
5365           <itemizedlist>
5366             <listitem>
5367               <para>Objekt der Klasse
5368               "<varname>SL::Dispatcher</varname>"</para>
5369             </listitem>
5370
5371             <listitem>
5372               <para>wird pro Serverprozess erstellt.</para>
5373             </listitem>
5374
5375             <listitem>
5376               <para>enthält Informationen über die technische Verbindung zum
5377               Server</para>
5378             </listitem>
5379           </itemizedlist>
5380
5381           <para>Der dritte Punkt ist auch der einzige Grund warum das Objekt
5382           global gespeichert wird. Wird vermutlich irgendwann in einem anderen
5383           Objekt untergebracht.</para>
5384         </sect3>
5385
5386         <sect3>
5387           <title>$::request</title>
5388
5389           <itemizedlist>
5390             <listitem>
5391               <para>Hashref (evtl später Objekt)</para>
5392             </listitem>
5393
5394             <listitem>
5395               <para>Wird pro Request neu initialisiert.</para>
5396             </listitem>
5397
5398             <listitem>
5399               <para>Keine Unterstruktur garantiert.</para>
5400             </listitem>
5401           </itemizedlist>
5402
5403           <para><varname>$::request</varname> ist ein generischer Platz um
5404           Daten "für den aktuellen Request" abzulegen. Sollte nicht für action
5405           at a distance benutzt werden, sondern um lokales memoizing zu
5406           ermöglichen, das garantiert am Ende des Requests zerstört
5407           wird.</para>
5408
5409           <para>Vieles von dem, was im moment in <varname>$::form</varname>
5410           liegt, sollte eigentlich hier liegen. Die groben
5411           Differentialkriterien sind:</para>
5412
5413           <itemizedlist>
5414             <listitem>
5415               <para>Kommt es vom User, und soll unverändert wieder an den
5416               User? Dann <varname>$::form</varname>, steht da eh schon</para>
5417             </listitem>
5418
5419             <listitem>
5420               <para>Sind es Daten aus der Datenbank, die nur bis zum Ende des
5421               Requests gebraucht werden? Dann
5422               <varname>$::request</varname></para>
5423             </listitem>
5424
5425             <listitem>
5426               <para>Muss ich von anderen Teilen des Programms lesend drauf
5427               zugreifen? Dann <varname>$::request</varname>, aber Zugriff über
5428               Wrappermethode</para>
5429             </listitem>
5430           </itemizedlist>
5431         </sect3>
5432       </sect2>
5433
5434       <sect2>
5435         <title>Ehemalige globale Variablen</title>
5436
5437         <para>Die folgenden Variablen waren einmal im Programm, und wurden
5438         entfernt.</para>
5439
5440         <sect3>
5441           <title>$::cgi</title>
5442
5443           <itemizedlist>
5444             <listitem>
5445               <para>war nötig, weil cookie Methoden nicht als
5446               Klassenfunktionen funktionieren</para>
5447             </listitem>
5448
5449             <listitem>
5450               <para>Aufruf als Klasse erzeugt Dummyobjekt was im
5451               Klassennamespace gehalten wird und über Requestgrenzen
5452               leaked</para>
5453             </listitem>
5454
5455             <listitem>
5456               <para>liegt jetzt unter
5457               <varname>$::request-&gt;{cgi}</varname></para>
5458             </listitem>
5459           </itemizedlist>
5460         </sect3>
5461
5462         <sect3>
5463           <title>$::all_units</title>
5464
5465           <itemizedlist>
5466             <listitem>
5467               <para>war nötig, weil einige Funktionen in Schleifen zum Teil
5468               ein paar hundert mal pro Request eine Liste der Einheiten
5469               brauchen, und de als Parameter durch einen Riesenstack von
5470               Funktionen geschleift werden müssten.</para>
5471             </listitem>
5472
5473             <listitem>
5474               <para>Liegt jetzt unter
5475               <varname>$::request-&gt;{cache}{all_units}</varname></para>
5476             </listitem>
5477
5478             <listitem>
5479               <para>Wird nur in
5480               <function>AM-&gt;retrieve_all_units()</function> gesetzt oder
5481               gelesen.</para>
5482             </listitem>
5483           </itemizedlist>
5484         </sect3>
5485
5486         <sect3>
5487           <title>%::called_subs</title>
5488
5489           <itemizedlist>
5490             <listitem>
5491               <para>wurde benutzt um callsub deep recursions
5492               abzufangen.</para>
5493             </listitem>
5494
5495             <listitem>
5496               <para>Wurde entfernt, weil callsub nur einen Bruchteil der
5497               möglichen Rekursioenen darstellt, und da nie welche
5498               auftreten.</para>
5499             </listitem>
5500
5501             <listitem>
5502               <para>komplette recursion protection wurde entfernt.</para>
5503             </listitem>
5504           </itemizedlist>
5505         </sect3>
5506       </sect2>
5507     </sect1>
5508
5509     <sect1 id="devel.fcgi">
5510       <title>Entwicklung unter FastCGI</title>
5511
5512       <sect2 id="devel.fcgi.general">
5513         <title>Allgemeines</title>
5514
5515         <para>Wenn Änderungen in der Konfiguration von kivitendo gemacht
5516         werden, muss der Webserver neu gestartet werden.</para>
5517
5518         <para>Bei der Entwicklung für FastCGI ist auf ein paar Fallstricke zu
5519         achten. Dadurch, dass das Programm in einer Endlosschleife läuft,
5520         müssen folgende Aspekte beachtet werden.</para>
5521       </sect2>
5522
5523       <sect2 id="devel.fcgi.exiting">
5524         <title>Programmende und Ausnahmen</title>
5525
5526         <para>Betrifft die Funktionen <function>warn</function>,
5527         <function>die</function>, <function>exit</function>,
5528         <function>carp</function> und <function>confess</function>.</para>
5529
5530         <para>Fehler, die dass Programm normalerweise sofort beenden (fatale
5531         Fehler), werden mit dem FastCGI Dispatcher abgefangen, um das Programm
5532         am Laufen zu halten. Man kann mit <function>die</function>,
5533         <function>confess</function> oder <function>carp</function> Fehler
5534         ausgeben, die dann vom Dispatcher angezeigt werden. Die kivitendo
5535         eigene <function>$::form-</function>error()&gt; tut im Prinzip das
5536         Gleiche, mit ein paar Extraoptionen. <function>warn</function> und
5537         <function>exit</function> hingegen werden nicht abgefangen.
5538         <function>warn</function> wird direkt nach STDERR, also in Server Log
5539         eine Nachricht schreiben (sofern in der Konfiguration nicht die
5540         Warnungen in das kivitendo Log umgeleitet wurden), und
5541         <function>exit</function> wird die Ausführung beenden.</para>
5542
5543         <para>Prinzipiell ist es kein Beinbruch, wenn sich der Prozess
5544         beendet, fcgi wird ihn sofort neu starten. Allerdings sollte das die
5545         Ausnahme sein. Quintessenz: Bitte kein <function>exit</function>
5546         benutzen, alle anderen Exceptionmechanismen sind ok.</para>
5547       </sect2>
5548
5549       <sect2 id="devel.fcgi.globals">
5550         <title>Globale Variablen</title>
5551
5552         <para>Um zu vermeiden, dass Informationen von einem Request in einen
5553         anderen gelangen, müssen alle globalen Variablen vor einem Request
5554         sauber initialisiert werden. Das ist besonders wichtig im
5555         <varname>$::cgi</varname> und <varname>$::auth</varname> Objekt, weil
5556         diese nicht gelöscht werden pro Instanz, sondern persistent gehalten
5557         werden.</para>
5558
5559         <para>In <classname>SL::Dispatcher</classname> gibt es einen sauber
5560         abgetrennten Block, der alle kanonischen globalen Variablen listet und
5561         erklärt. Bitte keine anderen einführen ohne das sauber zu
5562         dokumentieren.</para>
5563
5564         <para>Datenbankverbindungen wird noch ein Guide verfasst werden, wie
5565         man sicher geht, dass man die richtige erwischt.</para>
5566       </sect2>
5567
5568       <sect2 id="devel.fcgi.performance">
5569         <title>Performance und Statistiken</title>
5570
5571         <para>Die kritischen Pfade des Programms sind die Belegmasken, und
5572         unter diesen ganz besonders die Verkaufsrechnungsmaske. Ein Aufruf der
5573         Rechnungsmaske in kivitendo 2.4.3 stable dauert auf einem Core2duo mit
5574         4GB Arbeitsspeicher und Ubuntu 9.10 eine halbe Sekunde. In der 2.6.0
5575         sind es je nach Menge der definierten Variablen 1-2s. Ab der
5576         Moose/Rose::DB Version sind es 5-6s.</para>
5577
5578         <para>Mit FastCGI ist die neuste Version auf 0,26 Sekunden selbst in
5579         den kritischen Pfaden, unter 0,15 sonst.</para>
5580       </sect2>
5581     </sect1>
5582
5583     <sect1 id="db-upgrade-files" xreflabel="Datenbank-Upgradedateien">
5584       <title>SQL-Upgradedateien</title>
5585
5586       <sect2 id="db-upgrade-files.introduction"
5587              xreflabel="Einführung in die Datenbank-Upgradedateien">
5588         <title>Einführung</title>
5589
5590         <para>Datenbankupgrades werden über einzelne Upgrade-Scripte gesteuert, die sich im Verzeichnis <filename>sql/Pg-upgrade2</filename>
5591         befinden. In diesem Verzeichnis muss pro Datenbankupgrade eine Datei existieren, die neben den eigentlich auszuführenden SQL- oder
5592         Perl-Befehlen einige Kontrollinformationen enthält.</para>
5593
5594         <para>Kontrollinformationen definieren Abhängigkeiten und Prioritäten, sodass Datenbankscripte zwar in einer sicheren Reihenfolge
5595         ausgeführt werden (z.B. darf ein <literal>ALTER TABLE</literal> erst ausgeführt werden, wenn die Tabelle mit <literal>CREATE
5596         TABLE</literal> angelegt wurde), diese Reihenfolge aber so flexibel ist, dass man keine Versionsnummern braucht.</para>
5597
5598         <para>kivitendo merkt sich dabei, welches der Upgradescripte in <filename>sql/Pg-upgrade2</filename> bereits durchgeführt wurde und
5599         führt diese nicht erneut aus. Dazu dient die Tabelle "<literal>schema_info</literal>", die bei der Anmeldung automatisch angelegt
5600         wird.</para>
5601       </sect2>
5602
5603       <sect2 id="db-upgrade-files.format"
5604              xreflabel="Format der Upgradedateien">
5605         <title>Format der Kontrollinformationen</title>
5606
5607         <para>Die Kontrollinformationen sollten sich am Anfang der jeweiligen
5608         Upgradedatei befinden. Jede Zeile, die Kontrollinformationen enthält,
5609         hat dabei das folgende Format:</para>
5610
5611         <para>Für SQL-Upgradedateien:</para>
5612
5613         <programlisting>-- @key: value</programlisting>
5614
5615         <para>Für Perl-Upgradedateien:</para>
5616
5617         <programlisting># @key: value</programlisting>
5618
5619         <para>Leerzeichen vor "<varname>value</varname>" werden
5620         entfernt.</para>
5621
5622         <para>Die folgenden Schlüsselworte werden verarbeitet:</para>
5623
5624         <variablelist>
5625           <varlistentry>
5626             <term><varname>tag</varname></term>
5627
5628             <listitem>
5629               <para>Wird zwingend benötigt. Dies ist der "Name" des Upgrades.
5630               Dieser "tag" kann von anderen Kontrolldateien in ihren
5631               Abhängigkeiten verwendet werden (Schlüsselwort
5632               "<varname>depends</varname>"). Der "tag" ist auch der Name, der
5633               in der Datenbank eingetragen wird.</para>
5634
5635               <para>Normalerweise sollte die Kontrolldatei genau so heißen wie
5636               der "tag", nur mit der Endung ".sql" bzw. "pl".</para>
5637
5638               <para>Ein Tag darf nur aus alphanumerischen Zeichen sowie den
5639               Zeichen _ - ( ) bestehen. Insbesondere sind Leerzeichen nicht
5640               erlaubt und sollten stattdessen mit Unterstrichen ersetzt
5641               werden.</para>
5642             </listitem>
5643           </varlistentry>
5644
5645           <varlistentry>
5646             <term><varname>charset</varname></term>
5647
5648             <listitem>
5649               <para>Empfohlen. Gibt den Zeichensatz an, in dem das Script geschrieben wurde, z.B. "<literal>UTF-8</literal>". Aus
5650               Kompatibilitätsgründen mit alten Upgrade-Scripten wird bei Abwesenheit des Tags für SQL-Upgradedateien der Zeichensatz
5651               "<literal>ISO-8859-15</literal>" angenommen. Perl-Upgradescripte hingegen müssen immer in UTF-8 encodiert sein und sollten
5652               demnach auch ein "<literal>use utf8;</literal>" enthalten.</para>
5653             </listitem>
5654           </varlistentry>
5655
5656           <varlistentry>
5657             <term><varname>description</varname></term>
5658
5659             <listitem>
5660               <para>Benötigt. Eine Beschreibung, was in diesem Update
5661               passiert. Diese wird dem Benutzer beim eigentlichen
5662               Datenbankupdate angezeigt. Während der Tag in englisch gehalten
5663               sein sollte, sollte die Beschreibung auf Deutsch
5664               erfolgen.</para>
5665             </listitem>
5666           </varlistentry>
5667
5668           <varlistentry>
5669             <term><varname>depends</varname></term>
5670
5671             <listitem>
5672               <para>Optional. Eine mit Leerzeichen getrennte Liste von "tags",
5673               von denen dieses Upgradescript abhängt. kivitendo stellt sicher,
5674               dass die in dieser Liste aufgeführten Scripte bereits
5675               durchgeführt wurden, bevor dieses Script ausgeführt wird.</para>
5676
5677               <para>Abhängigkeiten werden rekursiv betrachtet. Wenn also ein
5678               Script "b" existiert, das von Änderungen in "a" abhängt, und
5679               eine neue Kontrolldatei für "c" erstellt wird, die von
5680               Änderungen in "a" und "b" abhängt, so genügt es, in "c" nur den
5681               Tag "b" als Abhängigkeit zu definieren.</para>
5682
5683               <para>Es ist nicht erlaubt, sich selbst referenzierende
5684               Abhängigkeiten zu definieren (z.B. "a" -&gt; "b", "b" -&gt; "c"
5685               und "c" -&gt; "a").</para>
5686             </listitem>
5687           </varlistentry>
5688
5689           <varlistentry>
5690             <term><varname>priority</varname></term>
5691
5692             <listitem>
5693               <para>Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in
5694               der Scripte ausgeführt werden, die die gleichen
5695               Abhängigkeitstiefen besitzen. Fehlt dieser Parameter, so wird
5696               der Wert 1000 benutzt.</para>
5697
5698               <para>Dies ist reine Kosmetik. Für echte Reihenfolgen muss
5699               "depends" benutzt werden. kivitendo sortiert die auszuführenden
5700               Scripte zuerst nach der Abhängigkeitstiefe (wenn "z" von "y"
5701               abhängt und "y" von "x", so hat "z" eine Abhängigkeitstiefe von
5702               2, "y" von 1 und "x" von 0. "x" würde hier zuerst ausgeführt,
5703               dann "y", dann "z"), dann nach der Priorität und bei gleicher
5704               Priorität alphabetisch nach dem "tag".</para>
5705             </listitem>
5706           </varlistentry>
5707
5708           <varlistentry>
5709             <term><varname>ignore</varname></term>
5710
5711             <listitem>
5712               <para>Optional. Falls der Wert auf 1 (true) steht, wird das
5713               Skript bei der Anmeldung ignoriert und entsprechend nicht
5714               ausgeführt.</para>
5715             </listitem>
5716           </varlistentry>
5717         </variablelist>
5718       </sect2>
5719
5720       <sect2 id="db-upgrade-files.format-perl-files" xreflabel="Format von Perl-Upgradedateien">
5721        <title>Format von in Perl geschriebenen Datenbankupgradescripten</title>
5722
5723        <para>In Perl geschriebene Datenbankscripte werden nicht einfach so ausgeführt sondern müssen sich an gewisse Konventionen
5724        halten. Dafür bekommen sie aber auch einige Komfortfunktionen bereitgestellt.</para>
5725
5726        <para>Ein Upgradescript stellt dabei eine vollständige Objektklasse dar, die vom Elternobjekt
5727        "<literal>SL::DBUpgrade2::Base</literal>" erben und eine Funktion namens "<literal>run</literal>" zur Verfügung stellen muss. Das
5728        Script wird ausgeführt, indem eine Instanz dieser Klasse erzeugt und darauf die erwähnte "<literal>run</literal>" aufgerufen
5729        wird.</para>
5730
5731        <para>Zu beachten ist, dass sich der Paketname der Datei aus dem Wert für "<literal>@tag</literal>" ableitet. Dabei werden alle
5732        Zeichen, die in Paketnamen ungültig wären (gerade Bindestriche), durch Unterstriche ersetzt. Insgesamt sieht der Paketname wie folgt
5733        aus: "<literal>SL::DBUpgrade2::tag</literal>".</para>
5734
5735        <para>Welche Komfortfunktionen zur Verfügung stehen, erfahren Sie in der Perl-Dokumentation zum oben genannten Modul; aufzurufen mit
5736        "<command>perldoc SL/DBUpgrade2/Base.pm</command>".</para>
5737
5738        <para>Ein Mindestgerüst eines gültigen Perl-Upgradescriptes sieht wie folgt aus:</para>
5739
5740        <programlisting># @tag: beispiel-upgrade-file42
5741 # @description: Ein schönes Beispielscript
5742 # @depends: release_3_1_0
5743 package SL::DBUpgrade2::beispiel_upgrade_file42;
5744
5745 use strict;
5746 use utf8;
5747
5748 use parent qw(SL::DBUpgrade2::Base);
5749
5750 sub run {
5751   my ($self) = @_;
5752
5753   # hier Aktionen ausführen
5754
5755   return 1;
5756 }
5757
5758 1;
5759 </programlisting>
5760       </sect2>
5761
5762       <sect2 id="db-upgrade-files.dbupgrade-tool"
5763              xreflabel="Hilfsscript dbupgrade2_tool.pl">
5764         <title>Hilfsscript dbupgrade2_tool.pl</title>
5765
5766         <para>Um die Arbeit mit den Abhängigkeiten etwas zu erleichtern,
5767         existiert ein Hilfsscript namens
5768         "<filename>scripts/dbupgrade2_tool.pl</filename>". Es muss aus dem
5769         kivitendo-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool
5770         liest alle Datenbankupgradescripte aus dem Verzeichnis
5771         <filename>sql/Pg-upgrade2</filename> aus. Es benutzt dafür die
5772         gleichen Methoden wie kivitendo selber, sodass alle Fehlersituationen
5773         von der Kommandozeile überprüft werden können.</para>
5774
5775         <para>Wird dem Script kein weiterer Parameter übergeben, so wird nur
5776         eine Überprüfung der Felder und Abhängigkeiten vorgenommen. Man kann
5777         sich aber auch Informationen auf verschiedene Art ausgeben
5778         lassen:</para>
5779
5780         <itemizedlist>
5781           <listitem>
5782             <para>Listenform: "<command>./scripts/dbupgrade2_tool.pl
5783             --list</command>"</para>
5784
5785             <para>Gibt eine Liste aller Scripte aus. Die Liste ist in der
5786             Reihenfolge sortiert, in der kivitendo die Scripte ausführen
5787             würde. Es werden neben der Listenposition der Tag, die
5788             Abhängigkeitstiefe und die Priorität ausgegeben.</para>
5789           </listitem>
5790
5791           <listitem>
5792             <para>Baumform: "<command>./scripts/dbupgrade2_tool.pl
5793             --tree</command>"</para>
5794
5795             <para>Listet alle Tags in Baumform basierend auf den
5796             Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte, von
5797             denen keine anderen abhängen. Die Unterknoten sind Scripte, die
5798             beim übergeordneten Script als Abhängigkeit eingetragen
5799             sind.</para>
5800           </listitem>
5801
5802           <listitem id="db-upgrade-files.dbupgrade-tool.reverse-tree">
5803             <para>Umgekehrte Baumform: "<command>./scripts/dbupgrade2_tool.pl
5804             --rtree</command>"</para>
5805
5806             <para>Listet alle Tags in Baumform basierend auf den
5807             Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte mit
5808             der geringsten Abhängigkeitstiefe. Die Unterknoten sind Scripte,
5809             die das übergeordnete Script als Abhängigkeit eingetragen
5810             haben.</para>
5811           </listitem>
5812
5813           <listitem>
5814             <para>Baumform mit Postscriptausgabe:
5815             "<command>./scripts/dbupgrade2_tool.pl
5816             --graphviz</command>"</para>
5817
5818             <para>Benötigt das Tool "<command>graphviz</command>", um mit
5819             seiner Hilfe die <link
5820             linkend="db-upgrade-files.dbupgrade-tool.reverse-tree">umgekehrte
5821             Baumform</link> in eine Postscriptdatei namens
5822             "<filename>db_dependencies.ps</filename>" auszugeben. Dies ist
5823             vermutlich die übersichtlichste Form, weil hierbei jeder Knoten
5824             nur einmal ausgegeben wird. Bei den Textmodusbaumformen hingegen
5825             können Knoten und all ihre Abhängigkeiten mehrfach ausgegeben
5826             werden.</para>
5827           </listitem>
5828
5829           <listitem>
5830             <para>Scripte, von denen kein anderes Script abhängt:
5831             "<command>./scripts/dbupgrade2_tool.pl --nodeps</command>"</para>
5832
5833             <para>Listet die Tags aller Scripte auf, von denen keine anderen
5834             Scripte abhängen.</para>
5835           </listitem>
5836         </itemizedlist>
5837       </sect2>
5838     </sect1>
5839
5840     <sect1 id="translations-languages" xreflabel="Translations and languages">
5841       <title>Translations and languages</title>
5842
5843       <sect2 id="translations-languages.introduction"
5844              xreflabel="Introduction to translations and languages">
5845         <title>Introduction</title>
5846
5847         <note>
5848           <para>Dieser Abschnitt ist in Englisch geschrieben, um
5849           internationalen Übersetzern die Arbeit zu erleichtern.</para>
5850         </note>
5851
5852         <para>This section describes how localization packages in kivitendo
5853         are built. Currently the only language fully supported is German, and
5854         since most of the internal messages are held in English the English
5855         version is usable too.</para>
5856
5857         <para>A stub version of French is included but not functunal at this
5858         point.</para>
5859       </sect2>
5860
5861       <sect2 id="translations-languages.character-set"
5862              xreflabel="Character set">
5863         <title>Character set</title>
5864
5865         <para>All files included in a language pack must use UTF-8 as their encoding.</para>
5866       </sect2>
5867
5868       <sect2 id="translations-languages.file-structure"
5869              xreflabel="File structure">
5870         <title>File structure</title>
5871
5872         <para>The structure of locales in kivitendo is:</para>
5873
5874         <programlisting>kivitendo/locale/&lt;langcode&gt;/</programlisting>
5875
5876         <para>where &lt;langcode&gt; stands for an abbreviation of the
5877         language package. The builtin packages use two letter <ulink
5878         url="http://en.wikipedia.org/wiki/ISO_639-1">ISO 639-1</ulink> codes,
5879         but the actual name is not relevant for the program and can easily be
5880         extended to <ulink
5881         url="http://en.wikipedia.org/wiki/IETF_language_tag">IETF language
5882         tags</ulink> (i.e. "en_GB"). In fact the original language packages
5883         from SQL Ledger are named in this way.</para>
5884
5885         <para>In such a language directory the following files are
5886         recognized:</para>
5887
5888         <variablelist>
5889           <varlistentry>
5890             <term>LANGUAGE</term>
5891
5892             <listitem>
5893               <para>This file is mandatory.</para>
5894
5895               <para>The <filename>LANGUAGE</filename> file contains the self
5896               descripted name of the language. It should contain a native
5897               representation first, and in parenthesis an english translation
5898               after that. Example:</para>
5899
5900               <programlisting>Deutsch (German)</programlisting>
5901             </listitem>
5902           </varlistentry>
5903
5904           <varlistentry>
5905             <term>all</term>
5906
5907             <listitem>
5908               <para>This file is mandatory.</para>
5909
5910               <para>The central translation file. It is essentially an inline
5911               Perl script autogenerated by <command>locales.pl</command>. To
5912               generate it, generate the directory and the two files mentioned
5913               above, and execute the following command:</para>
5914
5915               <programlisting>scripts/locales.pl &lt;langcode&gt;</programlisting>
5916
5917               <para>Otherwise you can simply copy one of the other languages.
5918               You will be told how many are missing like this:</para>
5919
5920               <programlisting>$ scripts/locales.pl en
5921 English - 0.6% - 2015/2028 missing</programlisting>
5922
5923               <para>A file named "<filename>missing</filename>" will be
5924               generated and can be edited. You can also edit the
5925               "<filename>all</filename>" file directly. Edit everything you
5926               like to fit the target language and execute
5927               <command>locales.pl</command> again. See how the missing words
5928               get fewer.</para>
5929             </listitem>
5930           </varlistentry>
5931
5932           <varlistentry>
5933             <term>Num2text</term>
5934
5935             <listitem>
5936               <para>Legacy code from SQL Ledger. It provides a means for
5937               numbers to be converted into natural language, like
5938               <literal>1523 =&gt; one thousand five hundred twenty
5939               three</literal>. If you want to provide it, it must be inlinable
5940               Perl code which provides a <function>num2text</function> sub. If
5941               an <function>init</function> sub exists it will be executed
5942               first.</para>
5943
5944               <para>Only used in the check and receipt printing module.</para>
5945             </listitem>
5946           </varlistentry>
5947
5948           <varlistentry>
5949             <term>special_chars</term>
5950
5951             <listitem>
5952               <para>kivitendo comes with a lot of interfaces to different
5953               formats, some of which are rather picky with their accepted
5954               charset. The <filename>special_chars</filename> file contains a
5955               listing of chars not suited for different file format and
5956               provides substitutions. It is written in "Simple Ini" style,
5957               containing a block for every file format.</para>
5958
5959               <para>First entry should be the order of substitution for
5960               entries as a whitespace separated list. All entries are
5961               interpolated, so <literal>\n</literal>, <literal>\x20</literal>
5962               and <literal>\\</literal> all work.</para>
5963
5964               <para>After that every entry is a special char that should be
5965               translated when writing text into such a file.</para>
5966
5967               <para>Example:</para>
5968
5969               <programlisting>[Template/XML]
5970 order=&amp; &lt; &gt; \n
5971 &amp;=&amp;amp;
5972 &lt;=&amp;lt;
5973 &gt;=&amp;gt;
5974 \n=&lt;br&gt;</programlisting>
5975
5976               <para>Note the importance of the order in this example.
5977               Substituting &lt; and &gt; befor &amp; would lead to $gt; become
5978               &amp;amp;gt;</para>
5979
5980               <para>For a list of valid formats, see the German
5981               <filename>special_chars</filename> entry. As of this writing the
5982               following are recognized:</para>
5983
5984               <programlisting>HTML
5985 URL@HTML
5986 Template/HTML
5987 Template/XML
5988 Template/LaTeX
5989 Template/OpenDocument
5990 filenames</programlisting>
5991
5992               <para>The last of which is very machine dependant. Remember that
5993               a lot of characters are forbidden by some filesystems, for
5994               exmaple MS Windows doesn't like ':' in its files where Linux
5995               doesn't mind that. If you want the files created with your
5996               language pack to be portable, find all chars that could cause
5997               trouble.</para>
5998             </listitem>
5999           </varlistentry>
6000
6001           <varlistentry>
6002             <term>missing</term>
6003
6004             <listitem>
6005               <para>This file is not a part of the language package
6006               itself.</para>
6007
6008               <para>This is a file generated by
6009               <command>scripts/locales.pl</command> while processing your
6010               locales. It's only to have the missing entries singled out and
6011               does not belong to a language package.</para>
6012             </listitem>
6013           </varlistentry>
6014
6015           <varlistentry>
6016             <term>lost</term>
6017
6018             <listitem>
6019               <para>This file is not a part of the language package
6020               itself.</para>
6021
6022               <para>Another file generated by
6023               <command>scripts/locales.pl</command>. If for any reason a
6024               translation does not appear anymore and can be deleted, it gets
6025               moved here. The last 50 or so entries deleted are saved here in
6026               case you made a typo, so that you don't have to translate
6027               everything again. If a tranlsation is missing, the lost file is
6028               checked first. If you maintain a language package, you might
6029               want to keep this safe somewhere.</para>
6030             </listitem>
6031           </varlistentry>
6032         </variablelist>
6033       </sect2>
6034     </sect1>
6035
6036     <sect1 id="devel.testsuite">
6037       <title>Die kivitendo-Test-Suite</title>
6038
6039       <sect2 id="devel.testsuite.intro">
6040         <title>Einführung</title>
6041
6042         <para>kivitendo enthält eine Suite für automatisierte Tests. Sie basiert auf dem Standard-Perl-Modul <literal>Test::More</literal>.</para>
6043
6044         <para>Die grundlegenden Fakten sind:</para>
6045
6046         <itemizedlist>
6047           <listitem><para>Alle Tests liegen im Unterverzeichnis <filename>t/</filename>.</para></listitem>
6048
6049           <listitem><para>Ein Script (bzw. ein Test) in <filename>t/</filename> enthält einen oder mehrere Testfälle.</para></listitem>
6050
6051           <listitem><para>Alle Dateinamen von Tests enden auf <literal>.t</literal>. Es sind selbstständig ausführbare Perl-Scripte.</para></listitem>
6052
6053           <listitem><para>Die Test-Suite besteht aus der Gesamtheit aller Tests, sprich aller Scripte in <filename>t/</filename>, deren
6054           Dateiname auf <literal>.t</literal> endet.</para></listitem>
6055         </itemizedlist>
6056       </sect2>
6057
6058       <sect2 id="devel.testsuite.prerequisites">
6059         <title>Voraussetzungen</title>
6060
6061         <para>Für die Ausführung werden neben den für kivitendo eh schon benötigten Module noch weitere Perl-Module benötigt. Diese sind:</para>
6062
6063         <itemizedlist>
6064           <listitem><para><literal>Test::Deep</literal> (Debian-Paketname: <literal>libtest-deep-perl</literal>; Fedora Core:
6065           <literal>perl-Test-Deep</literal>; openSUSE: <literal>perl-Test-Deep</literal>)</para></listitem>
6066           <listitem><para><literal>Test::Exception</literal> (Debian-Paketname: <literal>libtest-exception-perl</literal>; Fedora Core:
6067           <literal>perl-Test-Exception</literal>; openSUSE: <literal>perl-Test-Exception</literal>)</para></listitem>
6068           <listitem><para><literal>Test::Output</literal> (Debian-Paketname: <literal>libtest-output-perl</literal>; Fedora Core:
6069           <literal>perl-Test-Output</literal>; openSUSE: <literal>perl-Test-Output</literal>)</para></listitem>
6070           <listitem><para><literal>Test::Harness</literal> 3.0.0 oder höher. Dieses Modul ist ab Perl 5.10.1 Bestandteil der
6071           Perl-Distribution und kann für frühere Versionen aus dem <ulink url="http://www.cpan.org">CPAN</ulink> bezogen
6072           werden.</para></listitem>
6073           <listitem><para><literal>LWP::Simple</literal> aus dem Paket <literal>libwww-perl</literal> (Debian-Panetname:
6074           <literal>libwww-perl</literal>; Fedora Core: <literal>perl-libwww-perl</literal>; openSUSE:
6075           <literal>perl-libwww-perl</literal>)</para></listitem>
6076           <listitem><para><literal>URI::Find</literal> (Debian-Panetname: <literal>liburi-find-perl</literal>; Fedora Core:
6077           <literal>perl-URI-Find</literal>; openSUSE: <literal>perl-URI-Find</literal>)</para></listitem>
6078         </itemizedlist>
6079
6080         <para>Weitere Voraussetzung ist, dass die Testsuite ihre eigene Datenbank anlegen kann, um Produktivdaten nicht zu gefährden. Dazu
6081         müssen in der Konfigurationsdatei im Abschnit <literal>testing/database</literal> Datenbankverbindungsparameter angegeben
6082         werden. Der hier angegebene Benutzer muss weiterhin das Recht haben, Datenbanken anzulegen und zu löschen.</para>
6083       </sect2>
6084
6085       <sect2 id="devel.testsuite.execution">
6086         <title>
6087           Existierende Tests ausführen
6088         </title>
6089
6090         <para>Es gibt mehrere Möglichkeiten zum Ausführen der Tests: entweder, man lässt alle Tests auf einmal ausführen, oder man führt
6091         gezielt einzelne Scripte aus. Für beide Fälle gibt es das Helferscript <filename>t/test.pl</filename>.</para>
6092
6093         <para>Will man die komplette Test-Suite ausführen, so muss man einfach nur <filename>t/test.pl</filename> ohne weitere Parameter aus
6094         dem kivitendo-Basisverzeichnis heraus ausführen.</para>
6095
6096         <para>Um einzelne Test-Scripte auszuführen, übergibt man deren Namen an <filename>t/test.pl</filename>. Beispielsweise:</para>
6097
6098         <programlisting>t/test.pl t/form/format_amount.t t/background_job/known_jobs.t</programlisting>
6099       </sect2>
6100
6101
6102       <sect2 id="devel.testsuite.meaning_of_scripts">
6103         <title>
6104           Bedeutung der verschiedenen Test-Scripte
6105         </title>
6106
6107         <para>Die Test-Suite umfasst Tests sowohl für Funktionen als auch für Programmierstil. Einige besonders zu erwähnende, weil auch
6108         während der Entwicklung nützliche Tests sind:</para>
6109
6110         <itemizedlist>
6111           <listitem><para><filename>t/001compile.t</filename> -- compiliert alle Quelldateien und bricht bei Fehlern sofort ab</para></listitem>
6112           <listitem><para><filename>t/002goodperl.t</filename> -- überprüft alle Perl-Dateien auf Anwesenheit von '<literal>use strict</literal>'-Anweisungen</para></listitem>
6113           <listitem><para><filename>t/003safesys.t</filename> -- überprüft Aufrufe von <function>system()</function> und <function>exec()</function> auf Gültigkeit</para></listitem>
6114           <listitem><para><filename>t/005no_tabs.t</filename> -- überprüft, ob Dateien Tab-Zeichen enthalten</para></listitem>
6115           <listitem><para><filename>t/006spelling.t</filename> -- sucht nach häufigen Rechtschreibfehlern</para></listitem>
6116           <listitem><para><filename>t/011pod.t</filename> -- überprüft die Syntax von Dokumentation im POD-Format auf Gültigkeit</para></listitem>
6117         </itemizedlist>
6118
6119         <para>Weitere Test-Scripte überprüfen primär die Funktionsweise einzelner Funktionen und Module.</para>
6120       </sect2>
6121
6122       <sect2 id="devel.testsuite.create_new">
6123         <title>
6124           Neue Test-Scripte erstellen
6125         </title>
6126
6127         <para>Es wird sehr gern gesehen, wenn neue Funktionalität auch gleich mit einem Test-Script abgesichert wird. Auch bestehende
6128         Funktion darf und soll ausdrücklich nachträglich mit Test-Scripten abgesichert werden.</para>
6129
6130         <sect3 id="devel.testsuite.ideas_for_non_function_tests">
6131           <title>
6132             Ideen für neue Test-Scripte, die keine konkreten Funktionen testen
6133           </title>
6134
6135           <para> Ideen, die abgesehen von Funktionen noch nicht umgesetzt wurden:</para>
6136
6137           <itemizedlist>
6138             <listitem><para>Überprüfung auf fehlende symbolische Links</para></listitem>
6139             <listitem><para>Suche nach Nicht-ASCII-Zeichen in Perl-Code-Dateien (mit gewissen Einschränkungen wie das Erlauben von deutschen Umlauten)</para></listitem>
6140             <listitem><para>Test auf DOS-Zeilenenden (\r\n anstelle von nur \n)</para></listitem>
6141             <listitem><para>Überprüfung auf Leerzeichen am Ende von Zeilen</para></listitem>
6142             <listitem><para>Test, ob alle zu übersetzenden Strings in <filename>locale/de/all</filename> vorhanden sind</para></listitem>
6143             <listitem><para>Test, ob alle Webseiten-Templates in <filename>templates/webpages</filename> mit vom Perl-Modul <literal>Template</literal> compiliert werden können</para></listitem>
6144           </itemizedlist>
6145         </sect3>
6146
6147         <sect3 id="devel.testsuite.directory_and_test_names">
6148           <title>
6149             Konvention für Verzeichnis- und Dateinamen
6150           </title>
6151
6152           <para>Es gibt momentan eine wenige Richtlinien, wie Test-Scripte zu benennen sind. Bitte die folgenden Punkte als Richtlinie betrachten und ihnen soweit es geht folgen:</para>
6153
6154           <itemizedlist>
6155             <listitem><para>Die Dateiendung muss <filename>.t</filename> lauten.</para></listitem>
6156
6157             <listitem><para>Namen sind englisch, komplett klein geschrieben und einzelne Wörter mit Unterstrichten getrennt (beispielsweise
6158             <filename>bad_function_params.t</filename>).</para></listitem>
6159
6160             <listitem><para>Unterverzeichnisse sollten grob nach dem Themenbereich benannt sein, mit dem sich die Scripte darin befassen
6161             (beispielsweise <filename>background_jobs</filename> für Tests rund um Hintergrund-Jobs).</para></listitem>
6162
6163             <listitem><para>Test-Scripte sollten einen überschaubaren Bereich von Funktionalität testen, der logisch zusammenhängend ist
6164             (z.B. nur Tests für eine einzelne Funktion in einem Modul). Lieber mehrere Test-Scripte schreiben.</para></listitem>
6165           </itemizedlist>
6166         </sect3>
6167
6168         <sect3 id="devel.testsuite.minimal_example">
6169           <title>
6170             Minimales Skelett für eigene Scripte
6171           </title>
6172
6173           <para>Der folgenden Programmcode enthält das kleinstmögliche Testscript und kann als Ausgangspunkt für eigene Tests verwendet werden:</para>
6174
6175           <programlisting>use Test::More tests =&gt; 0;
6176
6177 use lib 't';
6178
6179 use Support::TestSetup;
6180
6181 Support::TestSetup::login();</programlisting>
6182
6183           <para>Wird eine vollständig initialisierte kivitendo-Umgebung benötigt (Stichwort: alle globalen Variablen wie
6184           <varname>$::auth</varname>, <varname>$::form</varname> oder <varname>$::lxdebug</varname>), so muss in der Konfigurationsdatei
6185           <filename>config/kivitendo.conf</filename> im Abschnitt <literal>testing.login</literal> ein gültiger Login-Name eingetragen
6186           sein. Dieser wird für die Datenbankverbindung benötigt.</para>
6187
6188           <para>Wir keine vollständig initialisierte Umgebung benötigt, so kann die letzte Zeile <code>Support::TestSetup::login();</code>
6189           weggelassen werden, was die Ausführungszeit des Scripts leicht verringert.</para>
6190         </sect3>
6191       </sect2>
6192     </sect1>
6193
6194     <sect1 id="devel.style-guide">
6195       <title>Stil-Richtlinien</title>
6196
6197       <para>Die folgenden Regeln haben das Ziel, den Code möglichst gut les-
6198       und wartbar zu machen. Dazu gehört zum Einen, dass der Code einheitlich
6199       eingerückt ist, aber auch, dass Mehrdeutigkeit so weit es geht vermieden
6200       wird (Stichworte "Klammern" oder "Hash-Keys").</para>
6201
6202       <para>Diese Regeln sind keine Schikane sondern erleichtern allen das
6203       Leben!</para>
6204
6205       <para>Jeder, der einen Patch schickt, sollte seinen Code vorher
6206       überprüfen. Einige der Regeln lassen sich automatisch überprüfen, andere
6207       nicht.</para>
6208
6209       <orderedlist>
6210         <listitem>
6211           <para>Es werden keine echten Tabs sondern Leerzeichen
6212           verwendet.</para>
6213         </listitem>
6214
6215         <listitem>
6216           <para>Die Einrückung beträgt zwei Leerzeichen. Beispiel:</para>
6217
6218           <programlisting>foreach my $row (@data) {
6219   if ($flag) {
6220     # do something with $row
6221   }
6222
6223   if ($use_modules) {
6224     $row-&gt;{modules} = MODULE-&gt;retrieve(
6225       id   =&gt; $row-&gt;{id},
6226       date =&gt; $use_now ? localtime() : $row-&gt;{time},
6227     );
6228   }
6229
6230   $report-&gt;add($row);
6231 }</programlisting>
6232         </listitem>
6233
6234         <listitem>
6235           <para>Öffnende geschweifte Klammern befinden sich auf der gleichen
6236           Zeile wie der letzte Befehl. Beispiele:</para>
6237
6238           <programlisting>sub debug {
6239   ...
6240 }</programlisting>
6241
6242           <para>oder</para>
6243
6244           <programlisting>if ($form-&gt;{item_rows} &gt; 0) {
6245   ...
6246 }</programlisting>
6247         </listitem>
6248
6249         <listitem>
6250           <para>Schließende geschweifte Klammern sind so weit eingerückt wie
6251           der Befehl / die öffnende schließende Klammer, die den Block
6252           gestartet hat, und nicht auf der Ebene des Inhalts. Die gleichen
6253           Beispiele wie bei 3. gelten.</para>
6254         </listitem>
6255
6256         <listitem>
6257           <para>Die Wörter "<function>else</function>",
6258           "<function>elsif</function>", "<function>while</function>" befinden
6259           sich auf der gleichen Zeile wie schließende geschweifte Klammern.
6260           Beispiele:</para>
6261
6262           <programlisting>if ($form-&gt;{sum} &gt; 1000) {
6263   ...
6264 } elsif ($form-&gt;{sum} &gt; 0) {
6265   ...
6266 } else {
6267   ...
6268 }
6269
6270 do {
6271   ...
6272 } until ($a &gt; 0);</programlisting>
6273         </listitem>
6274
6275         <listitem>
6276           <para>Parameter von Funktionsaufrufen müssen mit runden Klammern
6277           versehen werden. Davon nicht betroffen sind interne Perl-Funktionen,
6278           und grep-ähnliche Operatoren. Beispiel:</para>
6279
6280           <programlisting>$main::lxdebug-&gt;message("Could not find file.");
6281 %options = map { $_ =&gt; 1 } grep { !/^#/ } @config_file;</programlisting>
6282         </listitem>
6283
6284         <listitem>
6285           <para>Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen:</para>
6286
6287           <para>Generell gilt: Hashkeys und Arrayindices sollten nicht durch
6288           Leerzeichen abgesetzt werden. Logische Klammerungen ebensowenig,
6289           Blöcke schon. Beispiel:</para>
6290
6291           <programlisting>if (($form-&gt;{debug} == 1) &amp;&amp; ($form-&gt;{sum} - 100 &lt; 0)) {
6292   ...
6293 }
6294
6295 $array[$i + 1]             = 4;
6296 $form-&gt;{sum}              += $form-&gt;{"row_$i"};
6297 $form-&gt;{ $form-&gt;{index} } += 1;
6298
6299 map { $form-&gt;{sum} += $form-&gt;{"row_$_"} } 1..$rowcount;</programlisting>
6300         </listitem>
6301
6302         <listitem>
6303           <para>Mehrzeilige Befehle</para>
6304
6305           <orderedlist>
6306             <listitem>
6307               <para>Werden die Parameter eines Funktionsaufrufes auf mehrere
6308               Zeilen aufgeteilt, so sollten diese bis zu der Spalte eingerückt
6309               werden, in der die ersten Funktionsparameter in der ersten Zeile
6310               stehen. Beispiel:</para>
6311
6312               <programlisting>$sth = $dbh-&gt;prepare("SELECT * FROM some_table WHERE col = ?",
6313                     $form-&gt;{some_col_value});</programlisting>
6314             </listitem>
6315
6316             <listitem>
6317               <para>Ein Spezialfall ist der ternäre Oprator "?:", der am
6318               besten in einer übersichtlichen Tabellenstruktur organisiert
6319               wird. Beispiel:</para>
6320
6321               <programlisting>my $rowcount = $form-&gt;{"row_$i"} ? $i
6322              : $form-&gt;{oldcount} ? $form-&gt;{oldcount} + 1
6323              :                     $form-&gt;{rowcount} - $form-&gt;{rowbase};</programlisting>
6324             </listitem>
6325           </orderedlist>
6326         </listitem>
6327
6328         <listitem>
6329           <para>Kommentare</para>
6330
6331           <orderedlist>
6332             <listitem>
6333               <para>Kommentare, die alleine in einer Zeile stehen, sollten
6334               soweit wie der Code eingerückt sein.</para>
6335             </listitem>
6336
6337             <listitem>
6338               <para>Seitliche hängende Kommentare sollten einheitlich
6339               formatiert werden.</para>
6340             </listitem>
6341
6342             <listitem>
6343               <para>Sämtliche Kommentare und Sonstiges im Quellcode ist bitte
6344               auf Englisch zu verfassen. So wie ich keine Lust habe,
6345               französischen Quelltext zu lesen, sollte auch der kivitendo
6346               Quelltext für nicht-Deutschsprachige lesbar sein.
6347               Beispiel:</para>
6348
6349               <programlisting>my $found = 0;
6350 while (1) {
6351   last if $found;
6352
6353   # complicated check
6354   $found = 1 if //
6355 }
6356
6357 $i  = 0        # initialize $i
6358 $n  = $i;      # save $i
6359 $i *= $const;  # do something crazy
6360 $i  = $n;      # recover $i</programlisting>
6361             </listitem>
6362           </orderedlist>
6363         </listitem>
6364
6365         <listitem>
6366           <para>Hashkeys sollten nur in Anführungszeichen stehen, wenn die
6367           Interpolation gewünscht ist. Beispiel:</para>
6368
6369           <programlisting>$form-&gt;{sum}      = 0;
6370 $form-&gt;{"row_$i"} = $form-&gt;{"row_$i"} - 5;
6371 $some_hash{42}    = 54;</programlisting>
6372         </listitem>
6373
6374         <listitem>
6375           <para>Die maximale Zeilenlänge ist nicht beschränkt. Zeilenlängen
6376           unterhalb von 79 Zeichen helfen unter bestimmten Bedingungen, aber
6377           wenn die Lesbarkeit unter kurzen Zeilen leidet (wie zum Biespiel in
6378           grossen Tabellen), dann ist Lesbarkeit vorzuziehen.</para>
6379
6380           <para>Als Beispiel sei die Funktion
6381           <function>print_options</function> aus
6382           <filename>bin/mozilla/io.pl</filename> angeführt.</para>
6383         </listitem>
6384
6385         <listitem>
6386           <para>Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind
6387           unerwünscht. Sie führen zu unnötigen Whitespaceänderungen, die diffs
6388           verfälschen.</para>
6389
6390           <para>Emacs und vim haben beide recht einfache Methoden zur
6391           Entfernung von trailing whitespace. Emacs kennt das Kommande
6392           <command>nuke-trailing-whitespace</command>, vim macht das gleiche
6393           manuell über <literal>:%s/\s\+$//e</literal> Mit <literal>:au
6394           BufWritePre * :%s/\s\+$//e</literal> wird das an Speichern
6395           gebunden.</para>
6396         </listitem>
6397
6398         <listitem>
6399           <para>Es wird kein <command>perltidy</command> verwendet.</para>
6400
6401           <para>In der Vergangenheit wurde versucht,
6402           <command>perltidy</command> zu verwenden, um einen einheitlichen
6403           Stil zu erlangen. Es hat sich aber gezeigt, dass
6404           <command>perltidy</command>s sehr eigenwilliges Verhalten, was
6405           Zeilenumbrüche angeht, oftmals gut formatierten Code zerstört. Für
6406           den Interessierten sind hier die
6407           <command>perltidy</command>-Optionen, die grob den beschriebenen
6408           Richtlinien entsprechen:</para>
6409
6410           <programlisting>-syn -i=2 -nt -pt=2 -sbt=2 -ci=2 -ibc -hsc -noll -nsts -nsfs -asc -dsm
6411 -aws -bbc -bbs -bbb -mbl=1 -nsob -ce -nbl -nsbl -cti=0 -bbt=0 -bar -l=79
6412 -lp -vt=1 -vtc=1</programlisting>
6413         </listitem>
6414
6415         <listitem>
6416           <para><varname>STDERR</varname> ist tabu. Unkonditionale
6417           Debugmeldungen auch.</para>
6418
6419           <para>kivitendo bietet mit dem Modul <classname>LXDebug</classname>
6420           einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen
6421           Grund, nach <varname>STDERR</varname> zu schreiben.</para>
6422
6423           <para>Die <classname>LXDebug</classname>-Methode
6424           "<function>message</function>" nimmt als ersten Paramter außerdem
6425           eine Flagmaske, für die die Meldung angezeigt wird, wobei "0" immer
6426           angezeigt wird. Solche Meldungen sollten nicht eingecheckt werden
6427           und werden in den meisten Fällen auch vom Repository
6428           zurückgewiesen.</para>
6429         </listitem>
6430
6431         <listitem>
6432           <para>Alle neuen Module müssen use strict verwenden.</para>
6433
6434           <para><varname>$form</varname>, <varname>$auth</varname>,
6435           <varname>$locale</varname>, <varname>$lxdebug</varname> und
6436           <varname>%myconfig</varname> werden derzeit aus dem main package
6437           importiert (siehe <xref linkend="devel.globals" />. Alle anderen
6438           Konstrukte sollten lexikalisch lokal gehalten werden.</para>
6439         </listitem>
6440       </orderedlist>
6441     </sect1>
6442
6443     <sect1 id="devel.build-doc" xreflabel="Dokumentation erstellen">
6444       <title>Dokumentation erstellen</title>
6445
6446       <sect2 id="devel.build-doc.introduction">
6447         <title>Einführung</title>
6448
6449         <para>Diese Dokumentation ist in <productname>DocBook</productname>
6450         XML geschrieben. Zum Bearbeiten reicht grundsätzlich ein Text-Editor.
6451         Mehr Komfort bekommt man, wenn man einen dedizierten XML-fähigen
6452         Editor nutzt, der spezielle Unterstützung für
6453         <productname>DocBook</productname> mitbringt. Wir empfehlen dafür den
6454         <ulink url="http://www.xmlmind.com/xmleditor/">XMLmind XML
6455         Editor</ulink>, der bei nicht kommerzieller Nutzung kostenlos
6456         ist.</para>
6457       </sect2>
6458
6459       <sect2 id="devel.build-doc.required-software">
6460         <title>Benötigte Software</title>
6461
6462         <para>Bei <productname>DocBook</productname> ist Prinzip, dass
6463         ausschließlich die XML-Quelldatei bearbeitet wird. Aus dieser werden
6464         dann mit entsprechenden Stylesheets andere Formate wie PDF oder HTML
6465         erzeugt. Bei kivitendo übernimmt diese Aufgabe das Shell-Script
6466         <command>scripts/build_doc.sh</command>.</para>
6467
6468         <para>Das Script benötigt zur Konvertierung verschiedene
6469         Softwarekomponenten, die im normalen kivitendo-Betrieb nicht benötigt
6470         werden:</para>
6471
6472         <itemizedlist>
6473           <listitem>
6474             <para><ulink
6475             url="http://www.oracle.com/technetwork/java/index.html">Java</ulink>
6476             in einer halbwegs aktuellen Version</para>
6477           </listitem>
6478
6479           <listitem>
6480             <para>Das Java-Build-System <ulink
6481             url="http://ant.apache.org/">Apache Ant</ulink></para>
6482           </listitem>
6483
6484           <listitem>
6485             <para>Das Dokumentations-System Dobudish für
6486             <productname>DocBook</productname> 4.5, eine Zusammenstellung
6487             diverser Stylesheets und Grafiken zur Konvertierung von
6488             <productname>DocBook</productname> XML in andere Formate. Das
6489             Paket, das benötigt wird, ist zum Zeitpunkt der
6490             Dokumentationserstellung
6491             <filename>dobudish-nojre-1.1.4.zip</filename>, aus auf <ulink
6492             url="http://code.google.com/p/dobudish/downloads/list">code.google.com</ulink>
6493             bereitsteht.</para>
6494           </listitem>
6495         </itemizedlist>
6496
6497         <para>Apache Ant sowie ein dazu passendes Java Runtime Environment
6498         sind auf allen gängigen Plattformen verfügbar. Beispiel für
6499         Debian/Ubuntu:</para>
6500
6501         <programlisting>apt-get install ant openjdk-7-jre</programlisting>
6502
6503         <para>Nach dem Download von Dobudish muss Dobudish im Unterverzeichnis
6504         <filename>doc/build</filename> entpackt werden. Beispiel unter der
6505         Annahme, das <productname>Dobudish</productname> in
6506         <filename>$HOME/Downloads</filename> heruntergeladen wurde:</para>
6507
6508         <programlisting>cd doc/build
6509 unzip $HOME/Downloads/dobudish-nojre-1.1.4.zip</programlisting>
6510       </sect2>
6511
6512       <sect2 id="devel.build-doc.build">
6513         <title>PDFs und HTML-Seiten erstellen</title>
6514
6515         <para>Die eigentliche Konvertierung erfolgt nach Installation der
6516         benötigten Software mit einem einfachen Aufruf direkt aus dem
6517         kivitendo-Installationsverzeichnis heraus:</para>
6518
6519         <programlisting>./scripts/build_doc.sh</programlisting>
6520       </sect2>
6521
6522       <sect2 id="devel.build-doc.repository">
6523         <title>Einchecken in das Git-Repository</title>
6524
6525         <para>Sowohl die XML-Datei als auch die erzeugten PDF- und
6526         HTML-Dateien sind Bestandteil des Git-Repositories. Daraus folgt, dass
6527         nach Änderungen am XML die PDF- und HTML-Dokumente ebenfalls gebaut
6528         und alles zusammen in einem Commit eingecheckt werden sollten.</para>
6529
6530         <para>Die "<filename>dobudish</filename>"-Verzeichnisse bzw.
6531         symbolischen Links gehören hingegen nicht in das Repository.</para>
6532       </sect2>
6533     </sect1>
6534   </chapter>
6535 </book>