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