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