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