doc/dokumentation.xml

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