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