doc/dokumentation.xml

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