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