doc/dokumentation.xml

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