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