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