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