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