doc/dokumentation.xml

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