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