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.6.3 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.reports">
2174         <title>Auflisten</title>
2175
2176         <para>Unter Verkauf-&gt;Berichte-&gt;Aufträge finden sich zwei neue
2177         Checkboxen, "Wiederkehrende Rechnungen aktiv" und "Wiederkehrende
2178         Rechnungen inaktiv", mit denen man sich einen Überglick über die
2179         wiederkehrenden Rechnungen verschaffen kann.</para>
2180       </sect2>
2181
2182       <sect2 id="features.periodic-invoices.task-server">
2183         <title>Erzeugung der eigentlichen Rechnungen</title>
2184
2185         <para>Die zeitliche und periodische Überprüfung, ob eine
2186         wiederkehrende Rechnung automatisch erstellt werden soll, geschieht
2187         durch den <link linkend="config.task-server">Taskserver</link>, einen
2188         externen Dienst, der automatisch beim Start des Servers gestartet
2189         werden sollte.</para>
2190       </sect2>
2191
2192       <sect2 id="features.periodic-invoices.create-for-current-month">
2193         <title>Erste Rechnung für aktuellen Monat erstellen</title>
2194
2195         <para>Will man im laufenden Monat eine monatlich wiederkehrende
2196         Rechnung inkl. des laufenden Monats starten, stellt man das Startdatum
2197         auf den Monatsanfang und wartet ein paar Minuten, bis der Taskserver
2198         den neu konfigurieren Auftrag erkennt und daraus eine Rechnung
2199         generiert hat. Alternativ setzt man das Startdatum auf den
2200         Monatsersten des Folgemonats und erstellt die erste Rechnung direkt
2201         manuell über den Workflow.</para>
2202       </sect2>
2203     </sect1>
2204
2205     <sect1 id="dokumentenvorlagen-und-variablen">
2206       <title>Dokumentenvorlagen und verfügbare Variablen</title>
2207
2208       <sect2 id="dokumentenvorlagen-und-variablen.einführung">
2209         <title>Einführung</title>
2210
2211         <para>Dies ist eine Auflistung der Standard-Dokumentenvorlagen und
2212         aller zur Bearbeitung verfügbaren Variablen. Eine Variable wird in
2213         einer Vorlage durch ihren Inhalt ersetzt, wenn sie in der Form
2214         <function>&lt;%variablenname%&gt;</function> verwendet wird. Für
2215         LaTeX- und HTML-Vorlagen kann man die Form dieser Tags auch verändern
2216         (siehe <xref
2217         linkend="dokumentenvorlagen-und-variablen.tag-style" />).</para>
2218
2219         <para>Früher wurde hier nur über LaTeX gesprochen. Inzwischen
2220         unterstützt kivitendo aber auch OpenDocument-Vorlagen. Sofern es nicht
2221         ausdrücklich eingeschränkt wird, gilt das im Folgenden gesagte für
2222         alle Vorlagenarten.</para>
2223
2224         <para>Insgesamt sind technisch gesehen eine ganze Menge mehr Variablen
2225         verfügbar als hier aufgelistet werden. Die meisten davon können
2226         allerdings innerhalb einer solchen Vorlage nicht sinnvoll verwendet
2227         werden. Wenn eine Auflistung dieser Variablen gewollt ist, so kann
2228         diese wie folgt erhalten werden:</para>
2229
2230         <itemizedlist>
2231           <listitem>
2232             <para><filename>SL/Form.pm</filename> öffnen und am Anfang die
2233             Zeile "<command>use Data::Dumper;</command>" einfügen.</para>
2234           </listitem>
2235
2236           <listitem>
2237             <para>In <filename>Form.pm</filename> die Funktion
2238             <function>parse_template</function> suchen und hier die Zeile
2239             <command>print(STDERR Dumper($self));</command> einfügen.</para>
2240           </listitem>
2241
2242           <listitem>
2243             <para>Einmal per Browser die gewünschte Vorlage "benutzen", z.B.
2244             ein PDF für eine Rechnung erzeugen.</para>
2245           </listitem>
2246
2247           <listitem>
2248             <para>Im <filename>error.log</filename> Apache steht die Ausgabe
2249             der Variablen <varname>$self</varname> in der Form <varname>'key'
2250             =&gt; 'value',</varname>. Alle <varname>key</varname>s sind
2251             verfügbar.</para>
2252           </listitem>
2253         </itemizedlist>
2254       </sect2>
2255
2256       <sect2 id="dokumentenvorlagen-und-variablen.variablen-ausgeben">
2257         <title>Variablen ausgeben</title>
2258
2259         <para>Um eine Variable auszugeben, müssen sie einfach nur zwischen die
2260         Tags geschrieben werden, also z.B.
2261         <varname>&lt;%variablenname%&gt;</varname>.</para>
2262
2263         <para>Optional kann man auch mit Leerzeichen getrennte Flags angeben,
2264         die man aber nur selten brauchen wird. Die Syntax sieht also so aus:
2265         <varname>&lt;%variablenname FLAG1 FLAG2%&gt;</varname>. Momentan
2266         werden die folgenden Flags unterstützt:</para>
2267
2268         <itemizedlist>
2269           <listitem>
2270             <para><option>NOFORMAT</option> gilt nur für Zahlenwerte und gibt
2271             den Wert ohne Formatierung, also ohne Tausendertrennzeichen mit
2272             mit einem Punkt als Dezimaltrennzeichen aus. Nützlich z.B., wenn
2273             damit in der Vorlage z.B. von LaTeX gerechnet werden soll.</para>
2274           </listitem>
2275
2276           <listitem>
2277             <para><option>NOESCAPE</option> unterdrückt das Escapen von
2278             Sonderzeichen für die Vorlagensprache. Wenn also in einer
2279             Variablen bereits gültiger LaTeX-Code steht und dieser von LaTeX
2280             auch ausgewertet und nicht wortwörtlich angezeigt werden soll, so
2281             ist dieses Flag sinnvoll.</para>
2282           </listitem>
2283         </itemizedlist>
2284
2285         <para>Beispiel:</para>
2286
2287         <programlisting>&lt;%quototal NOFORMAT%&gt;</programlisting>
2288       </sect2>
2289
2290       <sect2 id="dokumentenvorlagen-und-variablen.verwendung-in-druckbefehlen">
2291         <title>Verwendung in Druckbefehlen</title>
2292
2293         <para>In der Admininstration können Drucker definiert werden. Auch im
2294         dort eingebbaren Druckbefehl können die hier aufgelisteten Variablen
2295         und Kontrollstrukturen verwendet werden. Ihr Inhalt wird dabei nach
2296         den Regeln der gängigen Shells formatiert, sodass Sonderzeichen wie
2297         <function>`...`</function> nicht zu unerwünschtem Verhalten
2298         führen.</para>
2299
2300         <para>Dies erlaubt z.B. die Definition eines Faxes als Druckerbefehl,
2301         für das die Telefonnummer eines Ansprechpartners als Teil der
2302         Kommandozeile verwendet wird. Für ein fiktives Kommando könnte das
2303         z.B. wie folgt aussehen:</para>
2304
2305         <programlisting>send_fax --number &lt;%if cp_phone2%&gt;&lt;%cp_phone2%&gt;&lt;%else%&gt;&lt;%cp_phone1%&gt;&lt;%end%&gt;</programlisting>
2306       </sect2>
2307
2308       <sect2 id="dokumentenvorlagen-und-variablen.tag-style"
2309              xreflabel="Anfang und Ende der Tags verändern">
2310         <title>Anfang und Ende der Tags verändern</title>
2311
2312         <para>Der Standardstil für Tags sieht vor, dass ein Tag mit dem
2313         Kleinerzeichen und einem Prozentzeichen beginnt und mit dem
2314         Prozentzeichen und dem Größerzeichen endet, beispielsweise
2315         <function>&lt;%customer%&gt;</function>. Da diese Form aber z.B. in
2316         LaTeX zu Problemen führen kann, weil das Prozentzeichen dort
2317         Kommentare einleitet, kann pro HTML- oder LaTeX-Dokumentenvorlage der
2318         Stil umgestellt werden.</para>
2319
2320         <para>Dazu werden in die Datei Zeilen geschrieben, die mit dem für das
2321         Format gültigen Kommentarzeichen anfangen, dann
2322         <function>config:</function> enthalten, die entsprechende Option
2323         setzen und bei HTML-Dokumentenvorlagen mit dem Kommentarendzeichen
2324         enden. Beispiel für LaTeX:</para>
2325
2326         <programlisting>% config: tag-style=($ $)</programlisting>
2327
2328         <para>Dies würde kivitendo dazu veranlassen, Variablen zu ersetzen,
2329         wenn sie wie folgt aussehen: <function>($customer$)</function>. Das
2330         äquivalente Beispiel für HTML-Dokumentenvorlagen sieht so aus:</para>
2331
2332         <programlisting>&lt;!-- config: tag-style=($ $) --&gt;</programlisting>
2333       </sect2>
2334
2335       <sect2 id="dokumentenvorlagen-und-variablen.zuordnung-dateinamen">
2336         <title>Zuordnung von den Dateinamen zu den Funktionen</title>
2337
2338         <para>Diese folgende kurze Auflistung zeigt, welche Vorlage bei
2339         welcher Funktion ausgelesen wird. Dabei ist die Dateiendung
2340         "<filename>.ext</filename>" geeignet zu ersetzen:
2341         "<filename>.tex</filename>" für LaTeX-Vorlagen und
2342         "<filename>.odt</filename>" für OpenDocument-Vorlagen.</para>
2343
2344         <variablelist>
2345           <varlistentry>
2346             <term><filename>bin_list.ext</filename></term>
2347
2348             <listitem>
2349               <para>Lagerliste</para>
2350             </listitem>
2351           </varlistentry>
2352
2353           <varlistentry>
2354             <term><filename>check.ext</filename></term>
2355
2356             <listitem>
2357               <para>?</para>
2358             </listitem>
2359           </varlistentry>
2360
2361           <varlistentry>
2362             <term><filename>invoice.ext</filename></term>
2363
2364             <listitem>
2365               <para>Rechnung</para>
2366             </listitem>
2367           </varlistentry>
2368
2369           <varlistentry>
2370             <term><filename>packing_list.ext</filename></term>
2371
2372             <listitem>
2373               <para>Packliste</para>
2374             </listitem>
2375           </varlistentry>
2376
2377           <varlistentry>
2378             <term><filename>pick_list.ext</filename></term>
2379
2380             <listitem>
2381               <para>Sammelliste</para>
2382             </listitem>
2383           </varlistentry>
2384
2385           <varlistentry>
2386             <term><filename>purchase_delivery_order.ext</filename></term>
2387
2388             <listitem>
2389               <para>Lieferschein (Einkauf)</para>
2390             </listitem>
2391           </varlistentry>
2392
2393           <varlistentry>
2394             <term><filename>purcharse_order.ext</filename></term>
2395
2396             <listitem>
2397               <para>Bestellung an Lieferanten</para>
2398             </listitem>
2399           </varlistentry>
2400
2401           <varlistentry>
2402             <term><filename>request_quotation.ext</filename></term>
2403
2404             <listitem>
2405               <para>Anfrage an Lieferanten</para>
2406             </listitem>
2407           </varlistentry>
2408
2409           <varlistentry>
2410             <term><filename>sales_delivery_order.ext</filename></term>
2411
2412             <listitem>
2413               <para>Lieferschein (Verkauf)</para>
2414             </listitem>
2415           </varlistentry>
2416
2417           <varlistentry>
2418             <term><filename>sales_order.ext</filename></term>
2419
2420             <listitem>
2421               <para>Bestellung</para>
2422             </listitem>
2423           </varlistentry>
2424
2425           <varlistentry>
2426             <term><filename>sales_quotation.ext</filename></term>
2427
2428             <listitem>
2429               <para>Angebot an Kunden</para>
2430             </listitem>
2431           </varlistentry>
2432
2433           <varlistentry>
2434             <term><filename>zahlungserinnerung.ext</filename></term>
2435
2436             <listitem>
2437               <para>Mahnung (Dateiname im Programm konfigurierbar)</para>
2438             </listitem>
2439           </varlistentry>
2440
2441           <varlistentry>
2442             <term><filename>zahlungserinnerung_invoice.ext</filename></term>
2443
2444             <listitem>
2445               <para>Rechnung über Mahngebühren (Dateiname im Programm
2446               konfigurierbar)</para>
2447             </listitem>
2448           </varlistentry>
2449         </variablelist>
2450       </sect2>
2451
2452       <sect2 id="dokumentenvorlagen-und-variablen.dateinamen-erweitert">
2453         <title>Sprache, Drucker und E-Mail</title>
2454
2455         <para>Angeforderte Sprache und Druckerkürzel in den Dateinamen mit
2456         eingearbeitet. So wird aus der Vorlage
2457         <filename>sales_order.ext</filename> bei Sprache
2458         <function>de</function> und Druckerkürzel <function>lpr2</function>
2459         der Vorlagenname <filename>sales_order_de_lpr2.ext</filename>.
2460         Zusätzlich können für E-Mails andere Vorlagen erstellt werden, diese
2461         bekommen dann noch das Kürzel <filename>_email</filename>, der
2462         vollständige Vorlagenname wäre dann
2463         <filename>sales_order_email_de_lpr2.ext</filename>. In allen Fällen
2464         kann eine Standarddatei <filename>default.ext</filename> hinterlegt
2465         werden. Diese wird verwendet, wenn keine der anderen Varianten
2466         gefunden wird.</para>
2467
2468         <para>Die vollständige Suchreihenfolge für einen Verkaufsauftrag mit
2469         der Sprache "de" und dem Drucker "lpr2", der per E-Mail im Format PDF
2470         verschickt wird, ist:</para>
2471
2472         <orderedlist>
2473           <listitem>
2474             <para><filename>sales_order_email_de_lpr2.tex</filename></para>
2475           </listitem>
2476
2477           <listitem>
2478             <para><filename>sales_order_de_lpr2.tex</filename></para>
2479           </listitem>
2480
2481           <listitem>
2482             <para><filename>sales_order.tex</filename></para>
2483           </listitem>
2484
2485           <listitem>
2486             <para><filename>default.tex</filename></para>
2487           </listitem>
2488         </orderedlist>
2489
2490         <para>Die kurzen Varianten dieser Vorlagentitel müssen dann entweder
2491         Standardwerte anzeigen, oder die angeforderten Werte selbst auswerten,
2492         siehe dazu <xref
2493         linkend="dokumentenvorlagen-und-variablen.allgemeine-variablen.meta" />.</para>
2494       </sect2>
2495
2496       <sect2 id="dokumentenvorlagen-und-variablen.allgemeine-variablen">
2497         <title>Allgemeine Variablen, die in allen Vorlagen vorhanden
2498         sind</title>
2499
2500         <sect3 id="dokumentenvorlagen-und-variablen.allgemeine-variablen.meta"
2501                xreflabel="Metainformationen zur angeforderten Vorlage">
2502           <title>Metainformationen zur angeforderten Vorlage</title>
2503
2504           <para>Diese Variablen liefern Informationen darüber welche Variante
2505           einer Vorlage der Benutzer angefragt hat. Sie sind nützlich für
2506           Vorlagenautoren, die aus einer zentralen Layoutvorlage die einzelnen
2507           Formulare einbinden möchten.</para>
2508
2509           <variablelist>
2510             <varlistentry>
2511               <term><varname>template_meta.formname</varname></term>
2512
2513               <listitem>
2514                 <para>Basisname der Vorlage. Identisch mit der <link
2515                 linkend="dokumentenvorlagen-und-variablen.zuordnung-dateinamen">Zurordnung
2516                 zu den Dateinamen</link> ohne die Erweiterung. Ein
2517                 Verkaufsauftrag enthält hier
2518                 <constant>sales_order</constant>.</para>
2519               </listitem>
2520             </varlistentry>
2521
2522             <varlistentry>
2523               <term><varname>template_meta.language.description</varname></term>
2524
2525               <listitem>
2526                 <para>Beschreibung der verwendeten Sprache</para>
2527               </listitem>
2528             </varlistentry>
2529
2530             <varlistentry>
2531               <term><varname>template_meta.language.template_code</varname></term>
2532
2533               <listitem>
2534                 <para>Vorlagenürzel der verwendeten Sprache, identisch mit dem
2535                 Kürzel das im Dateinamen verwendetet wird.</para>
2536               </listitem>
2537             </varlistentry>
2538
2539             <varlistentry>
2540               <term><varname>template_meta.language.output_numberformat</varname></term>
2541
2542               <listitem>
2543                 <para>Zahlenformat der verwendeten Sprache in der Form
2544                 "<constant>1.000,00</constant>". Experimentell! Nur
2545                 interessant für Vorlagen die mit unformatierten Werten
2546                 arbeiten.</para>
2547               </listitem>
2548             </varlistentry>
2549
2550             <varlistentry>
2551               <term><varname>template_meta.language.output_dateformat</varname></term>
2552
2553               <listitem>
2554                 <para>Datumsformat der verwendeten Sprache in der Form
2555                 "<constant>dd.mm.yyyy</constant>". Experimentell! Nur
2556                 interessant für Vorlagen die mit unformatierten Werten
2557                 arbeiten.</para>
2558               </listitem>
2559             </varlistentry>
2560
2561             <varlistentry>
2562               <term><varname>template_meta.format</varname></term>
2563
2564               <listitem>
2565                 <para>Das angeforderte Format. Kann im Moment die Werte
2566                 <constant>pdf</constant>, <constant>postscript</constant>,
2567                 <constant>html</constant>, <constant>opendocument</constant>,
2568                 <constant>opendocument_pdf</constant> und
2569                 <constant>excel</constant> enthalten.</para>
2570               </listitem>
2571             </varlistentry>
2572
2573             <varlistentry>
2574               <term><varname>template_meta.extension</varname></term>
2575
2576               <listitem>
2577                 <para>Dateierweiterung, wie im Dateinamen. Wird aus
2578                 <constant>format</constant> entschieden.</para>
2579               </listitem>
2580             </varlistentry>
2581
2582             <varlistentry>
2583               <term><varname>template_meta.media</varname></term>
2584
2585               <listitem>
2586                 <para>Ausgabemedium. Kann zur Zeit die Werte
2587                 <constant>screen</constant> für Bildschirm,
2588                 <constant>email</constant> für E-Mmail (triggert das
2589                 <constant>_email</constant> Kürzel im Dateinamen),
2590                 <constant>printer</constant> für Drucker, und
2591                 <constant>queue</constant> für Warteschlange enthalten.</para>
2592               </listitem>
2593             </varlistentry>
2594
2595             <varlistentry>
2596               <term><varname>template_meta.printer.description</varname></term>
2597
2598               <listitem>
2599                 <para>Beschreibung des ausgewählten Druckers</para>
2600               </listitem>
2601             </varlistentry>
2602
2603             <varlistentry>
2604               <term><varname>template_meta.printer.template_code</varname></term>
2605
2606               <listitem>
2607                 <para>Vorlagenürzel des ausgewählten Druckers, identisch mit
2608                 dem Kürzel das im Dateinamen verwendetet wird.</para>
2609               </listitem>
2610             </varlistentry>
2611
2612             <varlistentry>
2613               <term><varname>template_meta.tmpfile</varname></term>
2614
2615               <listitem>
2616                 <para>Datei-Prefix für temporäre Dateien.</para>
2617               </listitem>
2618             </varlistentry>
2619           </variablelist>
2620         </sect3>
2621
2622         <sect3 id="dokumentenvorlagen-und-variablen.allgemeine-variablen.kunden-lieferanten">
2623           <title>Stammdaten von Kunden und Lieferanten</title>
2624
2625           <variablelist>
2626             <varlistentry>
2627               <term><varname>account_number</varname></term>
2628
2629               <listitem>
2630                 <para>Kontonummer</para>
2631               </listitem>
2632             </varlistentry>
2633
2634             <varlistentry>
2635               <term><varname>bank</varname></term>
2636
2637               <listitem>
2638                 <para>Name der Bank</para>
2639               </listitem>
2640             </varlistentry>
2641
2642             <varlistentry>
2643               <term><varname>bank_code</varname></term>
2644
2645               <listitem>
2646                 <para>Bankleitzahl</para>
2647               </listitem>
2648             </varlistentry>
2649
2650             <varlistentry>
2651               <term><varname>bic</varname></term>
2652
2653               <listitem>
2654                 <para>Bank-Identifikations-Code (Bank Identifier Code,
2655                 BIC)</para>
2656               </listitem>
2657             </varlistentry>
2658
2659             <varlistentry>
2660               <term><varname>business</varname></term>
2661
2662               <listitem>
2663                 <para>Kunden-/Lieferantentyp</para>
2664               </listitem>
2665             </varlistentry>
2666
2667             <varlistentry>
2668               <term><varname>city</varname></term>
2669
2670               <listitem>
2671                 <para>Stadt</para>
2672               </listitem>
2673             </varlistentry>
2674
2675             <varlistentry>
2676               <term><varname>contact</varname></term>
2677
2678               <listitem>
2679                 <para>Kontakt</para>
2680               </listitem>
2681             </varlistentry>
2682
2683             <varlistentry>
2684               <term><varname>country</varname></term>
2685
2686               <listitem>
2687                 <para>Land</para>
2688               </listitem>
2689             </varlistentry>
2690
2691             <varlistentry>
2692               <term><varname>cp_email</varname></term>
2693
2694               <listitem>
2695                 <para>Email des Ansprechpartners</para>
2696               </listitem>
2697             </varlistentry>
2698
2699             <varlistentry>
2700               <term><varname>cp_givenname</varname></term>
2701
2702               <listitem>
2703                 <para>Vorname des Ansprechpartners</para>
2704               </listitem>
2705             </varlistentry>
2706
2707             <varlistentry>
2708               <term><varname>cp_greeting</varname></term>
2709
2710               <listitem>
2711                 <para>Anrede des Ansprechpartners</para>
2712               </listitem>
2713             </varlistentry>
2714
2715             <varlistentry>
2716               <term><varname>cp_name</varname></term>
2717
2718               <listitem>
2719                 <para>Name des Ansprechpartners</para>
2720               </listitem>
2721             </varlistentry>
2722
2723             <varlistentry>
2724               <term><varname>cp_phone1</varname></term>
2725
2726               <listitem>
2727                 <para>Telefonnummer 1 des Ansprechpartners</para>
2728               </listitem>
2729             </varlistentry>
2730
2731             <varlistentry>
2732               <term><varname>cp_phone2</varname></term>
2733
2734               <listitem>
2735                 <para>Telefonnummer 2 des Ansprechpartners</para>
2736               </listitem>
2737             </varlistentry>
2738
2739             <varlistentry>
2740               <term><varname>cp_title</varname></term>
2741
2742               <listitem>
2743                 <para>Titel des Ansprechpartners</para>
2744               </listitem>
2745             </varlistentry>
2746
2747             <varlistentry>
2748               <term><varname>creditlimit</varname></term>
2749
2750               <listitem>
2751                 <para>Kreditlimit</para>
2752               </listitem>
2753             </varlistentry>
2754
2755             <varlistentry>
2756               <term><varname>customeremail</varname></term>
2757
2758               <listitem>
2759                 <para>Email des Kunden; nur für Kunden</para>
2760               </listitem>
2761             </varlistentry>
2762
2763             <varlistentry>
2764               <term><varname>customerfax</varname></term>
2765
2766               <listitem>
2767                 <para>Faxnummer des Kunden; nur für Kunden</para>
2768               </listitem>
2769             </varlistentry>
2770
2771             <varlistentry>
2772               <term><varname>customernotes</varname></term>
2773
2774               <listitem>
2775                 <para>Bemerkungen beim Kunden; nur für Kunden</para>
2776               </listitem>
2777             </varlistentry>
2778
2779             <varlistentry>
2780               <term><varname>customernumber</varname></term>
2781
2782               <listitem>
2783                 <para>Kundennummer; nur für Kunden</para>
2784               </listitem>
2785             </varlistentry>
2786
2787             <varlistentry>
2788               <term><varname>customerphone</varname></term>
2789
2790               <listitem>
2791                 <para>Telefonnummer des Kunden; nur für Kunden</para>
2792               </listitem>
2793             </varlistentry>
2794
2795             <varlistentry>
2796               <term><varname>discount</varname></term>
2797
2798               <listitem>
2799                 <para>Rabatt</para>
2800               </listitem>
2801             </varlistentry>
2802
2803             <varlistentry>
2804               <term><varname>email</varname></term>
2805
2806               <listitem>
2807                 <para>Emailadresse</para>
2808               </listitem>
2809             </varlistentry>
2810
2811             <varlistentry>
2812               <term><varname>fax</varname></term>
2813
2814               <listitem>
2815                 <para>Faxnummer</para>
2816               </listitem>
2817             </varlistentry>
2818
2819             <varlistentry>
2820               <term><varname>homepage</varname></term>
2821
2822               <listitem>
2823                 <para>Homepage</para>
2824               </listitem>
2825             </varlistentry>
2826
2827             <varlistentry>
2828               <term><varname>iban</varname></term>
2829
2830               <listitem>
2831                 <para>Internationale Kontonummer (International Bank Account
2832                 Number, IBAN)</para>
2833               </listitem>
2834             </varlistentry>
2835
2836             <varlistentry>
2837               <term><varname>language</varname></term>
2838
2839               <listitem>
2840                 <para>Sprache</para>
2841               </listitem>
2842             </varlistentry>
2843
2844             <varlistentry>
2845               <term><varname>name</varname></term>
2846
2847               <listitem>
2848                 <para>Firmenname</para>
2849               </listitem>
2850             </varlistentry>
2851
2852             <varlistentry>
2853               <term><varname>payment_description</varname></term>
2854
2855               <listitem>
2856                 <para>Name der Zahlart</para>
2857               </listitem>
2858             </varlistentry>
2859
2860             <varlistentry>
2861               <term><varname>payment_terms</varname></term>
2862
2863               <listitem>
2864                 <para>Zahlungskonditionen</para>
2865               </listitem>
2866             </varlistentry>
2867
2868             <varlistentry>
2869               <term><varname>phone</varname></term>
2870
2871               <listitem>
2872                 <para>Telefonnummer</para>
2873               </listitem>
2874             </varlistentry>
2875
2876             <varlistentry>
2877               <term><varname>shiptocity</varname></term>
2878
2879               <listitem>
2880                 <para>Stadt (Lieferadresse) <link
2881                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
2882               </listitem>
2883             </varlistentry>
2884
2885             <varlistentry>
2886               <term><varname>shiptocontact</varname></term>
2887
2888               <listitem>
2889                 <para>Kontakt (Lieferadresse) <link
2890                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
2891               </listitem>
2892             </varlistentry>
2893
2894             <varlistentry>
2895               <term><varname>shiptocountry</varname></term>
2896
2897               <listitem>
2898                 <para>Land (Lieferadresse) <link
2899                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
2900               </listitem>
2901             </varlistentry>
2902
2903             <varlistentry>
2904               <term><varname>shiptodepartment1</varname></term>
2905
2906               <listitem>
2907                 <para>Abteilung 1 (Lieferadresse) <link
2908                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
2909               </listitem>
2910             </varlistentry>
2911
2912             <varlistentry>
2913               <term><varname>shiptodepartment2</varname></term>
2914
2915               <listitem>
2916                 <para>Abteilung 2 (Lieferadresse) <link
2917                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
2918               </listitem>
2919             </varlistentry>
2920
2921             <varlistentry>
2922               <term><varname>shiptoemail</varname></term>
2923
2924               <listitem>
2925                 <para>Email (Lieferadresse) <link
2926                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
2927               </listitem>
2928             </varlistentry>
2929
2930             <varlistentry>
2931               <term><varname>shiptofax</varname></term>
2932
2933               <listitem>
2934                 <para>Fax (Lieferadresse) <link
2935                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
2936               </listitem>
2937             </varlistentry>
2938
2939             <varlistentry>
2940               <term><varname>shiptoname</varname></term>
2941
2942               <listitem>
2943                 <para>Firmenname (Lieferadresse) <link
2944                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
2945               </listitem>
2946             </varlistentry>
2947
2948             <varlistentry>
2949               <term><varname>shiptophone</varname></term>
2950
2951               <listitem>
2952                 <para>Telefonnummer (Lieferadresse) <link
2953                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
2954               </listitem>
2955             </varlistentry>
2956
2957             <varlistentry>
2958               <term><varname>shiptostreet</varname></term>
2959
2960               <listitem>
2961                 <para>Straße und Hausnummer (Lieferadresse) <link
2962                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
2963               </listitem>
2964             </varlistentry>
2965
2966             <varlistentry>
2967               <term><varname>shiptozipcode</varname></term>
2968
2969               <listitem>
2970                 <para>Postleitzahl (Lieferadresse) <link
2971                 linkend="dokumentenvorlagen-und-variablen.anmerkung-shipto">*</link></para>
2972               </listitem>
2973             </varlistentry>
2974
2975             <varlistentry>
2976               <term><varname>street</varname></term>
2977
2978               <listitem>
2979                 <para>Straße und Hausnummer</para>
2980               </listitem>
2981             </varlistentry>
2982
2983             <varlistentry>
2984               <term><varname>taxnumber</varname></term>
2985
2986               <listitem>
2987                 <para>Steuernummer</para>
2988               </listitem>
2989             </varlistentry>
2990
2991             <varlistentry>
2992               <term><varname>ustid</varname></term>
2993
2994               <listitem>
2995                 <para>Umsatzsteuer-Identifikationsnummer</para>
2996               </listitem>
2997             </varlistentry>
2998
2999             <varlistentry>
3000               <term><varname>vendoremail</varname></term>
3001
3002               <listitem>
3003                 <para>Email des Lieferanten; nur für Lieferanten</para>
3004               </listitem>
3005             </varlistentry>
3006
3007             <varlistentry>
3008               <term><varname>vendorfax</varname></term>
3009
3010               <listitem>
3011                 <para>Faxnummer des Lieferanten; nur für Lieferanten</para>
3012               </listitem>
3013             </varlistentry>
3014
3015             <varlistentry>
3016               <term><varname>vendornotes</varname></term>
3017
3018               <listitem>
3019                 <para>Bemerkungen beim Lieferanten; nur für Lieferanten</para>
3020               </listitem>
3021             </varlistentry>
3022
3023             <varlistentry>
3024               <term><varname>vendornumber</varname></term>
3025
3026               <listitem>
3027                 <para>Lieferantennummer; nur für Lieferanten</para>
3028               </listitem>
3029             </varlistentry>
3030
3031             <varlistentry>
3032               <term><varname>vendorphone</varname></term>
3033
3034               <listitem>
3035                 <para>Telefonnummer des Lieferanten; nur für
3036                 Lieferanten</para>
3037               </listitem>
3038             </varlistentry>
3039
3040             <varlistentry>
3041               <term><varname>zipcode</varname></term>
3042
3043               <listitem>
3044                 <para>Postleitzahl</para>
3045               </listitem>
3046             </varlistentry>
3047           </variablelist>
3048
3049           <note id="dokumentenvorlagen-und-variablen.anmerkung-shipto">
3050             <para>Anmerkung: Sind die <varname>shipto*</varname>-Felder in den
3051             Stammdaten nicht eingetragen, so haben die Variablen
3052             <varname>shipto*</varname> den gleichen Wert wie die die
3053             entsprechenden Variablen der Lieferdaten. Das bedeutet, dass sich
3054             einige <varname>shipto*</varname>-Variablen so nicht in den
3055             Stammdaten wiederfinden sondern schlicht Kopien der
3056             Lieferdatenvariablen sind (z.B.
3057             <varname>shiptocontact</varname>).</para>
3058           </note>
3059         </sect3>
3060
3061         <sect3 id="dokumentenvorlagen-und-variablen.allgemein-bearbeiter">
3062           <title>Informationen über den Bearbeiter</title>
3063
3064           <variablelist>
3065             <varlistentry>
3066               <term><varname>employee_address</varname></term>
3067
3068               <listitem>
3069                 <para>Adressfeld</para>
3070               </listitem>
3071             </varlistentry>
3072
3073             <varlistentry>
3074               <term><varname>employee_businessnumber</varname></term>
3075
3076               <listitem>
3077                 <para>Firmennummer</para>
3078               </listitem>
3079             </varlistentry>
3080
3081             <varlistentry>
3082               <term><varname>employee_company</varname></term>
3083
3084               <listitem>
3085                 <para>Firmenname</para>
3086               </listitem>
3087             </varlistentry>
3088
3089             <varlistentry>
3090               <term><varname>employee_co_ustid</varname></term>
3091
3092               <listitem>
3093                 <para>Usatzsteuer-Identifikationsnummer</para>
3094               </listitem>
3095             </varlistentry>
3096
3097             <varlistentry>
3098               <term><varname>employee_duns</varname></term>
3099
3100               <listitem>
3101                 <para>DUNS-Nummer</para>
3102               </listitem>
3103             </varlistentry>
3104
3105             <varlistentry>
3106               <term><varname>employee_email</varname></term>
3107
3108               <listitem>
3109                 <para>Email</para>
3110               </listitem>
3111             </varlistentry>
3112
3113             <varlistentry>
3114               <term><varname>employee_fax</varname></term>
3115
3116               <listitem>
3117                 <para>Fax</para>
3118               </listitem>
3119             </varlistentry>
3120
3121             <varlistentry>
3122               <term><varname>employee_name</varname></term>
3123
3124               <listitem>
3125                 <para>voller Name</para>
3126               </listitem>
3127             </varlistentry>
3128
3129             <varlistentry>
3130               <term><varname>employee_signature</varname></term>
3131
3132               <listitem>
3133                 <para>Signatur</para>
3134               </listitem>
3135             </varlistentry>
3136
3137             <varlistentry>
3138               <term><varname>employee_taxnumber</varname></term>
3139
3140               <listitem>
3141                 <para>Steuernummer</para>
3142               </listitem>
3143             </varlistentry>
3144
3145             <varlistentry>
3146               <term><varname>employee_tel</varname></term>
3147
3148               <listitem>
3149                 <para>Telefonnummer</para>
3150               </listitem>
3151             </varlistentry>
3152           </variablelist>
3153         </sect3>
3154
3155         <sect3 id="dokumentenvorlagen-und-variablen.allgemein-verkaeufer">
3156           <title>Informationen über den Bearbeiter</title>
3157
3158           <variablelist>
3159             <varlistentry>
3160               <term><varname>salesman_address</varname></term>
3161
3162               <listitem>
3163                 <para>Adressfeld</para>
3164               </listitem>
3165             </varlistentry>
3166
3167             <varlistentry>
3168               <term><varname>salesman_businessnumber</varname></term>
3169
3170               <listitem>
3171                 <para>Firmennummer</para>
3172               </listitem>
3173             </varlistentry>
3174
3175             <varlistentry>
3176               <term><varname>salesman_company</varname></term>
3177
3178               <listitem>
3179                 <para>Firmenname</para>
3180               </listitem>
3181             </varlistentry>
3182
3183             <varlistentry>
3184               <term><varname>salesman_co_ustid</varname></term>
3185
3186               <listitem>
3187                 <para>Usatzsteuer-Identifikationsnummer</para>
3188               </listitem>
3189             </varlistentry>
3190
3191             <varlistentry>
3192               <term><varname>salesman_duns</varname></term>
3193
3194               <listitem>
3195                 <para>DUNS-Nummer</para>
3196               </listitem>
3197             </varlistentry>
3198
3199             <varlistentry>
3200               <term><varname>salesman_email</varname></term>
3201
3202               <listitem>
3203                 <para>Email</para>
3204               </listitem>
3205             </varlistentry>
3206
3207             <varlistentry>
3208               <term><varname>salesman_fax</varname></term>
3209
3210               <listitem>
3211                 <para>Fax</para>
3212               </listitem>
3213             </varlistentry>
3214
3215             <varlistentry>
3216               <term><varname>salesman_name</varname></term>
3217
3218               <listitem>
3219                 <para>voller Name</para>
3220               </listitem>
3221             </varlistentry>
3222
3223             <varlistentry>
3224               <term><varname>salesman_signature</varname></term>
3225
3226               <listitem>
3227                 <para>Signatur</para>
3228               </listitem>
3229             </varlistentry>
3230
3231             <varlistentry>
3232               <term><varname>salesman_taxnumber</varname></term>
3233
3234               <listitem>
3235                 <para>Steuernummer</para>
3236               </listitem>
3237             </varlistentry>
3238
3239             <varlistentry>
3240               <term><varname>salesman_tel</varname></term>
3241
3242               <listitem>
3243                 <para>Telefonnummer</para>
3244               </listitem>
3245             </varlistentry>
3246           </variablelist>
3247         </sect3>
3248
3249         <sect3 id="dokumentenvorlagen-und-variablen.allgemein-steuern">
3250           <title>Variablen für die einzelnen Steuern</title>
3251
3252           <variablelist>
3253             <varlistentry>
3254               <term><varname>tax</varname></term>
3255
3256               <listitem>
3257                 <para>Steuer</para>
3258               </listitem>
3259             </varlistentry>
3260
3261             <varlistentry>
3262               <term><varname>taxbase</varname></term>
3263
3264               <listitem>
3265                 <para>zu versteuernder Betrag</para>
3266               </listitem>
3267             </varlistentry>
3268
3269             <varlistentry>
3270               <term><varname>taxdescription</varname></term>
3271
3272               <listitem>
3273                 <para>Name der Steuer</para>
3274               </listitem>
3275             </varlistentry>
3276
3277             <varlistentry>
3278               <term><varname>taxrate</varname></term>
3279
3280               <listitem>
3281                 <para>Steuersatz</para>
3282               </listitem>
3283             </varlistentry>
3284           </variablelist>
3285         </sect3>
3286       </sect2>
3287
3288       <sect2 id="dokumentenvorlagen-und-variablen.invoice">
3289         <title>Variablen in Rechnungen</title>
3290
3291         <sect3 id="dokumentenvorlagen-und-variablen.invoice-allgemein">
3292           <title>Allgemeine Variablen</title>
3293
3294           <variablelist>
3295             <varlistentry>
3296               <term><varname>creditremaining</varname></term>
3297
3298               <listitem>
3299                 <para>Verbleibender Kredit</para>
3300               </listitem>
3301             </varlistentry>
3302
3303             <varlistentry>
3304               <term><varname>currency</varname></term>
3305
3306               <listitem>
3307                 <para>Währung</para>
3308               </listitem>
3309             </varlistentry>
3310
3311             <varlistentry>
3312               <term><varname>cusordnumber</varname></term>
3313
3314               <listitem>
3315                 <para>Bestellnummer beim Kunden</para>
3316               </listitem>
3317             </varlistentry>
3318
3319             <varlistentry>
3320               <term><varname>deliverydate</varname></term>
3321
3322               <listitem>
3323                 <para>Lieferdatum</para>
3324               </listitem>
3325             </varlistentry>
3326
3327             <varlistentry>
3328               <term><varname>duedate</varname></term>
3329
3330               <listitem>
3331                 <para>Fälligkeitsdatum</para>
3332               </listitem>
3333             </varlistentry>
3334
3335             <varlistentry>
3336               <term><varname>globalprojectnumber</varname></term>
3337
3338               <listitem>
3339                 <para>Projektnummer des ganzen Beleges</para>
3340               </listitem>
3341             </varlistentry>
3342
3343             <varlistentry>
3344               <term><varname>globalprojectdescription</varname></term>
3345
3346               <listitem>
3347                 <para>Projekbeschreibung des ganzen Beleges</para>
3348               </listitem>
3349             </varlistentry>
3350
3351             <varlistentry>
3352               <term><varname>intnotes</varname></term>
3353
3354               <listitem>
3355                 <para>Interne Bemerkungen</para>
3356               </listitem>
3357             </varlistentry>
3358
3359             <varlistentry>
3360               <term><varname>invdate</varname></term>
3361
3362               <listitem>
3363                 <para>Rechnungsdatum</para>
3364               </listitem>
3365             </varlistentry>
3366
3367             <varlistentry>
3368               <term><varname>invnumber</varname></term>
3369
3370               <listitem>
3371                 <para>Rechnungsnummer</para>
3372               </listitem>
3373             </varlistentry>
3374
3375             <varlistentry>
3376               <term><varname>invtotal</varname></term>
3377
3378               <listitem>
3379                 <para>gesamter Rechnungsbetrag</para>
3380               </listitem>
3381             </varlistentry>
3382
3383             <varlistentry>
3384               <term><varname>notes</varname></term>
3385
3386               <listitem>
3387                 <para>Bemerkungen der Rechnung</para>
3388               </listitem>
3389             </varlistentry>
3390
3391             <varlistentry>
3392               <term><varname>orddate</varname></term>
3393
3394               <listitem>
3395                 <para>Auftragsdatum</para>
3396               </listitem>
3397             </varlistentry>
3398
3399             <varlistentry>
3400               <term><varname>ordnumber</varname></term>
3401
3402               <listitem>
3403                 <para>Auftragsnummer, wenn die Rechnung aus einem Auftrag
3404                 erstellt wurde</para>
3405               </listitem>
3406             </varlistentry>
3407
3408             <varlistentry>
3409               <term><varname>payment_description</varname></term>
3410
3411               <listitem>
3412                 <para>Name der Zahlart</para>
3413               </listitem>
3414             </varlistentry>
3415
3416             <varlistentry>
3417               <term><varname>payment_terms</varname></term>
3418
3419               <listitem>
3420                 <para>Zahlungskonditionen</para>
3421               </listitem>
3422             </varlistentry>
3423
3424             <varlistentry>
3425               <term><varname>quodate</varname></term>
3426
3427               <listitem>
3428                 <para>Angebotsdatum</para>
3429               </listitem>
3430             </varlistentry>
3431
3432             <varlistentry>
3433               <term><varname>quonumber</varname></term>
3434
3435               <listitem>
3436                 <para>Angebotsnummer</para>
3437               </listitem>
3438             </varlistentry>
3439
3440             <varlistentry>
3441               <term><varname>shippingpoint</varname></term>
3442
3443               <listitem>
3444                 <para>Versandort</para>
3445               </listitem>
3446             </varlistentry>
3447
3448             <varlistentry>
3449               <term><varname>shipvia</varname></term>
3450
3451               <listitem>
3452                 <para>Transportmittel</para>
3453               </listitem>
3454             </varlistentry>
3455
3456             <varlistentry>
3457               <term><varname>subtotal</varname></term>
3458
3459               <listitem>
3460                 <para>Zwischensumme aller Posten ohne Steuern</para>
3461               </listitem>
3462             </varlistentry>
3463
3464             <varlistentry>
3465               <term><varname>total</varname></term>
3466
3467               <listitem>
3468                 <para>Restsumme der Rechnung (Summe abzüglich bereits
3469                 bezahlter Posten)</para>
3470               </listitem>
3471             </varlistentry>
3472
3473             <varlistentry>
3474               <term><varname>transaction_description</varname></term>
3475
3476               <listitem>
3477                 <para>Vorgangsbezeichnung</para>
3478               </listitem>
3479             </varlistentry>
3480
3481             <varlistentry>
3482               <term><varname>transdate</varname></term>
3483
3484               <listitem>
3485                 <para>Auftragsdatum wenn die Rechnung aus einem Auftrag
3486                 erstellt wurde</para>
3487               </listitem>
3488             </varlistentry>
3489           </variablelist>
3490         </sect3>
3491
3492         <sect3 id="dokumentenvorlagen-und-variablen.invoice-posten">
3493           <title>Variablen für jeden Posten auf der Rechnung</title>
3494
3495           <variablelist>
3496             <varlistentry>
3497               <term><varname>bin</varname></term>
3498
3499               <listitem>
3500                 <para>Stellage</para>
3501               </listitem>
3502             </varlistentry>
3503
3504             <varlistentry>
3505               <term><varname>description</varname></term>
3506
3507               <listitem>
3508                 <para>Artikelbeschreibung</para>
3509               </listitem>
3510             </varlistentry>
3511
3512             <varlistentry>
3513               <term><varname>discount</varname></term>
3514
3515               <listitem>
3516                 <para>Rabatt als Betrag</para>
3517               </listitem>
3518             </varlistentry>
3519
3520             <varlistentry>
3521               <term><varname>discount_sub</varname></term>
3522
3523               <listitem>
3524                 <para>Zwischensumme mit Rabatt</para>
3525               </listitem>
3526             </varlistentry>
3527
3528             <varlistentry>
3529               <term><varname>drawing</varname></term>
3530
3531               <listitem>
3532                 <para>Zeichnung</para>
3533               </listitem>
3534             </varlistentry>
3535
3536             <varlistentry>
3537               <term><varname>ean</varname></term>
3538
3539               <listitem>
3540                 <para>EAN-Code</para>
3541               </listitem>
3542             </varlistentry>
3543
3544             <varlistentry>
3545               <term><varname>image</varname></term>
3546
3547               <listitem>
3548                 <para>Grafik</para>
3549               </listitem>
3550             </varlistentry>
3551
3552             <varlistentry>
3553               <term><varname>linetotal</varname></term>
3554
3555               <listitem>
3556                 <para>Zeilensumme (Anzahl * Einzelpreis)</para>
3557               </listitem>
3558             </varlistentry>
3559
3560             <varlistentry>
3561               <term><varname>longdescription</varname></term>
3562
3563               <listitem>
3564                 <para>Langtext</para>
3565               </listitem>
3566             </varlistentry>
3567
3568             <varlistentry>
3569               <term><varname>microfiche</varname></term>
3570
3571               <listitem>
3572                 <para>Mikrofilm</para>
3573               </listitem>
3574             </varlistentry>
3575
3576             <varlistentry>
3577               <term><varname>netprice</varname></term>
3578
3579               <listitem>
3580                 <para>Nettopreis</para>
3581               </listitem>
3582             </varlistentry>
3583
3584             <varlistentry>
3585               <term><varname>nodiscount_linetotal</varname></term>
3586
3587               <listitem>
3588                 <para>Zeilensumme ohne Rabatt</para>
3589               </listitem>
3590             </varlistentry>
3591
3592             <varlistentry>
3593               <term><varname>nodiscount_sub</varname></term>
3594
3595               <listitem>
3596                 <para>Zwischensumme ohne Rabatt</para>
3597               </listitem>
3598             </varlistentry>
3599
3600             <varlistentry>
3601               <term><varname>number</varname></term>
3602
3603               <listitem>
3604                 <para>Artikelnummer</para>
3605               </listitem>
3606             </varlistentry>
3607
3608             <varlistentry>
3609               <term><varname>ordnumber_oe</varname></term>
3610
3611               <listitem>
3612                 <para>Auftragsnummer des Originalauftrags, wenn die Rechnung
3613                 aus einem Sammelauftrag erstellt wurde</para>
3614               </listitem>
3615             </varlistentry>
3616
3617             <varlistentry>
3618               <term><varname>p_discount</varname></term>
3619
3620               <listitem>
3621                 <para>Rabatt in Prozent</para>
3622               </listitem>
3623             </varlistentry>
3624
3625             <varlistentry>
3626               <term><varname>partnotes</varname></term>
3627
3628               <listitem>
3629                 <para>Die beim Artikel gespeicherten Bemerkungen</para>
3630               </listitem>
3631             </varlistentry>
3632
3633             <varlistentry>
3634               <term><varname>partsgroup</varname></term>
3635
3636               <listitem>
3637                 <para>Warengruppe</para>
3638               </listitem>
3639             </varlistentry>
3640
3641             <varlistentry>
3642               <term><varname>price_factor</varname></term>
3643
3644               <listitem>
3645                 <para>Der Preisfaktor als Zahl, sofern einer eingestellt
3646                 ist</para>
3647               </listitem>
3648             </varlistentry>
3649
3650             <varlistentry>
3651               <term><varname>price_factor_name</varname></term>
3652
3653               <listitem>
3654                 <para>Der Name des Preisfaktors, sofern einer eingestellt
3655                 ist</para>
3656               </listitem>
3657             </varlistentry>
3658
3659             <varlistentry>
3660               <term><varname>projectnumber</varname></term>
3661
3662               <listitem>
3663                 <para>Projektnummer</para>
3664               </listitem>
3665             </varlistentry>
3666
3667             <varlistentry>
3668               <term><varname>projectdescription</varname></term>
3669
3670               <listitem>
3671                 <para>Projektbeschreibung</para>
3672               </listitem>
3673             </varlistentry>
3674
3675             <varlistentry>
3676               <term><varname>qty</varname></term>
3677
3678               <listitem>
3679                 <para>Anzahl</para>
3680               </listitem>
3681             </varlistentry>
3682
3683             <varlistentry>
3684               <term><varname>reqdate</varname></term>
3685
3686               <listitem>
3687                 <para>Lieferdatum</para>
3688               </listitem>
3689             </varlistentry>
3690
3691             <varlistentry>
3692               <term><varname>runningnumber</varname></term>
3693
3694               <listitem>
3695                 <para>Position auf der Rechnung (1, 2, 3...)</para>
3696               </listitem>
3697             </varlistentry>
3698
3699             <varlistentry>
3700               <term><varname>sellprice</varname></term>
3701
3702               <listitem>
3703                 <para>Verkaufspreis</para>
3704               </listitem>
3705             </varlistentry>
3706
3707             <varlistentry>
3708               <term><varname>serialnumber</varname></term>
3709
3710               <listitem>
3711                 <para>Seriennummer</para>
3712               </listitem>
3713             </varlistentry>
3714
3715             <varlistentry>
3716               <term><varname>tax_rate</varname></term>
3717
3718               <listitem>
3719                 <para>Steuersatz</para>
3720               </listitem>
3721             </varlistentry>
3722
3723             <varlistentry>
3724               <term><varname>transdate_oe</varname></term>
3725
3726               <listitem>
3727                 <para>Auftragsdatum des Originalauftrags, wenn die Rechnung
3728                 aus einem Sammelauftrag erstellt wurde</para>
3729               </listitem>
3730             </varlistentry>
3731
3732             <varlistentry>
3733               <term><varname>unit</varname></term>
3734
3735               <listitem>
3736                 <para>Einheit</para>
3737               </listitem>
3738             </varlistentry>
3739
3740             <varlistentry>
3741               <term><varname>weight</varname></term>
3742
3743               <listitem>
3744                 <para>Gewicht</para>
3745               </listitem>
3746             </varlistentry>
3747           </variablelist>
3748
3749           <para>Für jeden Posten gibt es ein Unterarray mit den Informationen
3750           über Lieferanten und Lieferantenartikelnummer. Diese müssen mit
3751           einer <function>foreach</function>-Schleife ausgegeben werden, da
3752           für jeden Artikel mehrere Lieferanteninformationen hinterlegt sein
3753           können. Die Variablen dafür lauten:</para>
3754
3755           <variablelist>
3756             <varlistentry>
3757               <term><varname>make</varname></term>
3758
3759               <listitem>
3760                 <para>Lieferant</para>
3761               </listitem>
3762             </varlistentry>
3763
3764             <varlistentry>
3765               <term><varname>model</varname></term>
3766
3767               <listitem>
3768                 <para>Lieferantenartikelnummer</para>
3769               </listitem>
3770             </varlistentry>
3771           </variablelist>
3772         </sect3>
3773
3774         <sect3 id="dokumentenvorlagen-und-variablen.invoice-zahlungen">
3775           <title>Variablen für die einzelnen Zahlungseingänge</title>
3776
3777           <variablelist>
3778             <varlistentry>
3779               <term><varname>payment</varname></term>
3780
3781               <listitem>
3782                 <para>Betrag</para>
3783               </listitem>
3784             </varlistentry>
3785
3786             <varlistentry>
3787               <term><varname>paymentaccount</varname></term>
3788
3789               <listitem>
3790                 <para>Konto</para>
3791               </listitem>
3792             </varlistentry>
3793
3794             <varlistentry>
3795               <term><varname>paymentdate</varname></term>
3796
3797               <listitem>
3798                 <para>Datum</para>
3799               </listitem>
3800             </varlistentry>
3801
3802             <varlistentry>
3803               <term><varname>paymentmemo</varname></term>
3804
3805               <listitem>
3806                 <para>Memo</para>
3807               </listitem>
3808             </varlistentry>
3809
3810             <varlistentry>
3811               <term><varname>paymentsource</varname></term>
3812
3813               <listitem>
3814                 <para>Beleg</para>
3815               </listitem>
3816             </varlistentry>
3817           </variablelist>
3818         </sect3>
3819
3820         <sect3 id="dokumentenvorlagen-und-variablen.benutzerdefinierte-variablen-vc">
3821           <title>Benutzerdefinierte Kunden- und Lieferantenvariablen</title>
3822
3823           <para>Die vom Benutzer definierten Variablen für Kunden und
3824           Lieferanten stehen beim Ausdruck von Einkaufs- und Verkaufsbelegen
3825           ebenfalls zur Verfügung. Ihre Namen setzen sich aus dem Präfix
3826           <varname>vc_cvar_</varname> und dem vom Benutzer festgelegten
3827           Variablennamen zusammen.</para>
3828
3829           <para>Beispiel: Der Benutzer hat eine Variable namens
3830           <varname>number_of_employees</varname> definiert, die die Anzahl der
3831           Mitarbeiter des Unternehmens enthält. Diese Variable steht dann
3832           unter dem Namen <varname>vc_cvar_number_of_employees</varname> zur
3833           Verfügung.</para>
3834         </sect3>
3835       </sect2>
3836
3837       <sect2 id="dokumentenvorlagen-und-variablen.dunning">
3838         <title>Variablen in Mahnungen und Rechnungen über Mahngebühren</title>
3839
3840         <sect3 id="dokumentenvorlagen-und-variablen.dunning-vorlagennamen">
3841           <title>Namen der Vorlagen</title>
3842
3843           <para>Die Namen der Vorlagen werden im System-Menü vom Benutzer
3844           eingegeben. Wird für ein Mahnlevel die Option zur automatischen
3845           Erstellung einer Rechnung über die Mahngebühren und Zinsen
3846           aktiviert, so wird der Name der Vorlage für diese Rechnung aus dem
3847           Vorlagenname für diese Mahnstufe mit dem Zusatz
3848           <constant>_invoice</constant> gebildet. Weiterhin werden die Kürzel
3849           für die ausgewählte Sprache und den ausgewählten Drucker
3850           angehängt.</para>
3851         </sect3>
3852
3853         <sect3 id="dokumentenvorlagen-und-variablen.dunning-allgemein">
3854           <title>Allgemeine Variablen in Mahnungen</title>
3855
3856           <para>Die Variablen des Verkäufers stehen wie gewohnt als
3857           <varname>employee_...</varname> zur Verfügung. Die Adressdaten des
3858           Kunden stehen als Variablen <varname>name</varname>,
3859           <varname>street</varname>, <varname>zipcode</varname>,
3860           <varname>city</varname>, <varname>country</varname>,
3861           <varname>department_1</varname>, <varname>department_2</varname>,
3862           und <varname>email</varname> zur Verfügung.</para>
3863
3864           <para>Weitere Variablen beinhalten:</para>
3865
3866           <variablelist>
3867             <varlistentry>
3868               <term><varname>dunning_date</varname></term>
3869
3870               <listitem>
3871                 <para>Datum der Mahnung</para>
3872               </listitem>
3873             </varlistentry>
3874
3875             <varlistentry>
3876               <term><varname>dunning_duedate</varname></term>
3877
3878               <listitem>
3879                 <para>Fälligkeitsdatum für diese Mahhnung</para>
3880               </listitem>
3881             </varlistentry>
3882
3883             <varlistentry>
3884               <term><varname>dunning_id</varname></term>
3885
3886               <listitem>
3887                 <para>Mahnungsnummer</para>
3888               </listitem>
3889             </varlistentry>
3890
3891             <varlistentry>
3892               <term><varname>fee</varname></term>
3893
3894               <listitem>
3895                 <para>Kummulative Mahngebühren</para>
3896               </listitem>
3897             </varlistentry>
3898
3899             <varlistentry>
3900               <term><varname>interest_rate</varname></term>
3901
3902               <listitem>
3903                 <para>Zinssatz per anno in Prozent</para>
3904               </listitem>
3905             </varlistentry>
3906
3907             <varlistentry>
3908               <term><varname>total_amount</varname></term>
3909
3910               <listitem>
3911                 <para>Gesamter noch zu zahlender Betrag als
3912                 <function>fee</function> + <function>total_interest</function>
3913                 + <function>total_open_amount</function></para>
3914               </listitem>
3915             </varlistentry>
3916
3917             <varlistentry>
3918               <term><varname>total_interest</varname></term>
3919
3920               <listitem>
3921                 <para>Zinsen per anno über alle Rechnungen</para>
3922               </listitem>
3923             </varlistentry>
3924
3925             <varlistentry>
3926               <term><varname>total_open_amount</varname></term>
3927
3928               <listitem>
3929                 <para>Summe über alle offene Beträge der Rechnungen</para>
3930               </listitem>
3931             </varlistentry>
3932           </variablelist>
3933         </sect3>
3934
3935         <sect3 id="dokumentenvorlagen-und-variablen.dunning-details">
3936           <title>Variablen für jede gemahnte Rechnung in einer Mahnung</title>
3937
3938           <variablelist>
3939             <varlistentry>
3940               <term><varname>dn_amount</varname></term>
3941
3942               <listitem>
3943                 <para>Rechnungssumme (brutto)</para>
3944               </listitem>
3945             </varlistentry>
3946
3947             <varlistentry>
3948               <term><varname>dn_duedate</varname></term>
3949
3950               <listitem>
3951                 <para>Originales Fälligkeitsdatum der Rechnung</para>
3952               </listitem>
3953             </varlistentry>
3954
3955             <varlistentry>
3956               <term><varname>dn_dunning_date</varname></term>
3957
3958               <listitem>
3959                 <para>Datum der Mahnung</para>
3960               </listitem>
3961             </varlistentry>
3962
3963             <varlistentry>
3964               <term><varname>dn_dunning_duedate</varname></term>
3965
3966               <listitem>
3967                 <para>Fälligkeitsdatum der Mahnung</para>
3968               </listitem>
3969             </varlistentry>
3970
3971             <varlistentry>
3972               <term><varname>dn_fee</varname></term>
3973
3974               <listitem>
3975                 <para>Kummulative Mahngebühr</para>
3976               </listitem>
3977             </varlistentry>
3978
3979             <varlistentry>
3980               <term><varname>dn_interest</varname></term>
3981
3982               <listitem>
3983                 <para>Zinsen per anno für diese Rechnung</para>
3984               </listitem>
3985             </varlistentry>
3986
3987             <varlistentry>
3988               <term><varname>dn_invnumber</varname></term>
3989
3990               <listitem>
3991                 <para>Rechnungsnummer</para>
3992               </listitem>
3993             </varlistentry>
3994
3995             <varlistentry>
3996               <term><varname>dn_linetotal</varname></term>
3997
3998               <listitem>
3999                 <para>Noch zu zahlender Betrag (ergibt sich aus
4000                 <varname>dn_open_amount</varname> + <varname>dn_fee</varname>
4001                 + <varname>dn_interest</varname>)</para>
4002               </listitem>
4003             </varlistentry>
4004
4005             <varlistentry>
4006               <term><varname>dn_netamount</varname></term>
4007
4008               <listitem>
4009                 <para>Rechnungssumme (netto)</para>
4010               </listitem>
4011             </varlistentry>
4012
4013             <varlistentry>
4014               <term><varname>dn_open_amount</varname></term>
4015
4016               <listitem>
4017                 <para>Offener Rechnungsbetrag</para>
4018               </listitem>
4019             </varlistentry>
4020
4021             <varlistentry>
4022               <term><varname>dn_ordnumber</varname></term>
4023
4024               <listitem>
4025                 <para>Bestellnummer</para>
4026               </listitem>
4027             </varlistentry>
4028
4029             <varlistentry>
4030               <term><varname>dn_transdate</varname></term>
4031
4032               <listitem>
4033                 <para>Rechnungsdatum</para>
4034               </listitem>
4035             </varlistentry>
4036
4037             <varlistentry>
4038               <term><varname>dn_curr</varname></term>
4039
4040               <listitem>
4041                 <para>Währung, in der die Rechnung erstellt wurde. (Die
4042                 Rechnungsbeträge sind aber immer in der Hauptwährung)</para>
4043               </listitem>
4044             </varlistentry>
4045           </variablelist>
4046         </sect3>
4047
4048         <sect3 id="dokumentenvorlagen-und-variablen.dunning-invoice">
4049           <title>Variablen in automatisch erzeugten Rechnungen über
4050           Mahngebühren</title>
4051
4052           <para>Die Variablen des Verkäufers stehen wie gewohnt als
4053           <varname>employee_...</varname> zur Verfügung. Die Adressdaten des
4054           Kunden stehen als Variablen <varname>name</varname>,
4055           <varname>street</varname>, <varname>zipcode</varname>,
4056           <varname>city</varname>, <varname>country</varname>,
4057           <varname>department_1</varname>, <varname>department_2</varname>,
4058           und <varname>email</varname> zur Verfügung.</para>
4059
4060           <para>Weitere Variablen beinhalten:</para>
4061
4062           <variablelist>
4063             <varlistentry>
4064               <term><varname>duedate</varname></term>
4065
4066               <listitem>
4067                 <para>Fälligkeitsdatum der Rechnung</para>
4068               </listitem>
4069             </varlistentry>
4070
4071             <varlistentry>
4072               <term><varname>dunning_id</varname></term>
4073
4074               <listitem>
4075                 <para>Mahnungsnummer</para>
4076               </listitem>
4077             </varlistentry>
4078
4079             <varlistentry>
4080               <term><varname>fee</varname></term>
4081
4082               <listitem>
4083                 <para>Mahngebühren</para>
4084               </listitem>
4085             </varlistentry>
4086
4087             <varlistentry>
4088               <term><varname>interest</varname></term>
4089
4090               <listitem>
4091                 <para>Zinsen</para>
4092               </listitem>
4093             </varlistentry>
4094
4095             <varlistentry>
4096               <term><varname>invamount</varname></term>
4097
4098               <listitem>
4099                 <para>Rechnungssumme (ergibt sich aus <varname>fee</varname> +
4100                 <varname>interest</varname>)</para>
4101               </listitem>
4102             </varlistentry>
4103
4104             <varlistentry>
4105               <term><varname>invdate</varname></term>
4106
4107               <listitem>
4108                 <para>Rechnungsdatum</para>
4109               </listitem>
4110             </varlistentry>
4111
4112             <varlistentry>
4113               <term><varname>invnumber</varname></term>
4114
4115               <listitem>
4116                 <para>Rechnungsnummer</para>
4117               </listitem>
4118             </varlistentry>
4119           </variablelist>
4120         </sect3>
4121       </sect2>
4122
4123       <sect2 id="dokumentenvorlagen-und-variablen.andere-vorlagen">
4124         <title>Variablen in anderen Vorlagen</title>
4125
4126         <sect3>
4127           <title>Einführung</title>
4128
4129           <para>Die Variablen in anderen Vorlagen sind ähnlich wie in der
4130           Rechnung. Allerdings heißen die Variablen, die mit
4131           <varname>inv</varname> beginnen, jetzt anders. Bei den Angeboten
4132           fangen sie mit <varname>quo</varname> für "quotation" an:
4133           <varname>quodate</varname> für Angebotsdatum etc. Bei Bestellungen
4134           wiederum fangen sie mit <varname>ord</varname> für "order" an:
4135           <varname>ordnumber</varname> für Bestellnummer etc.</para>
4136
4137           <para>Manche Variablen sind in anderen Vorlagen hingegen gar nicht
4138           vorhanden wie z.B. die für bereits verbuchte Zahlungseingänge. Dies
4139           sind Variablen, die vom Geschäftsablauf her in der entsprechenden
4140           Vorlage keine Bedeutung haben oder noch nicht belegt sein
4141           können.</para>
4142
4143           <para>Im Folgenden werden nur wichtige Unterschiede zu den Variablen
4144           in Rechnungen aufgeführt.</para>
4145         </sect3>
4146
4147         <sect3 id="dokumentenvorlagen-und-variablen.andere-vorlagen-quotations">
4148           <title>Angebote und Preisanfragen</title>
4149
4150           <variablelist>
4151             <varlistentry>
4152               <term><varname>quonumber</varname></term>
4153
4154               <listitem>
4155                 <para>Angebots- bzw. Anfragenummer</para>
4156               </listitem>
4157             </varlistentry>
4158
4159             <varlistentry>
4160               <term><varname>reqdate</varname></term>
4161
4162               <listitem>
4163                 <para>Gültigkeitsdatum (bei Angeboten) bzw. Lieferdatum (bei
4164                 Preisanfragen)</para>
4165               </listitem>
4166             </varlistentry>
4167
4168             <varlistentry>
4169               <term><varname>transdate</varname></term>
4170
4171               <listitem>
4172                 <para>Angebots- bzw. Anfragedatum</para>
4173               </listitem>
4174             </varlistentry>
4175           </variablelist>
4176         </sect3>
4177
4178         <sect3 id="dokumentenvorlagen-und-variablen.andere-vorlagen-orders">
4179           <title>Auftragsbestätigungen und Lieferantenaufträge</title>
4180
4181           <variablelist>
4182             <varlistentry>
4183               <term><varname>ordnumber</varname></term>
4184
4185               <listitem>
4186                 <para>Auftragsnummer</para>
4187               </listitem>
4188             </varlistentry>
4189
4190             <varlistentry>
4191               <term><varname>reqdate</varname></term>
4192
4193               <listitem>
4194                 <para>Lieferdatum</para>
4195               </listitem>
4196             </varlistentry>
4197
4198             <varlistentry>
4199               <term><varname>transdate</varname></term>
4200
4201               <listitem>
4202                 <para>Auftragsdatum</para>
4203               </listitem>
4204             </varlistentry>
4205           </variablelist>
4206         </sect3>
4207
4208         <sect3 id="dokumentenvorlagen-und-variablen.andere-vorlagen-delivery-orders">
4209           <title>Lieferscheine (Verkauf und Einkauf)</title>
4210
4211           <variablelist>
4212             <varlistentry>
4213               <term><varname>cusordnumber</varname></term>
4214
4215               <listitem>
4216                 <para>Bestellnummer des Kunden (im Verkauf) bzw. Bestellnummer
4217                 des Lieferanten (im Einkauf)</para>
4218               </listitem>
4219             </varlistentry>
4220
4221             <varlistentry>
4222               <term><varname>donumber</varname></term>
4223
4224               <listitem>
4225                 <para>Lieferscheinnummer</para>
4226               </listitem>
4227             </varlistentry>
4228
4229             <varlistentry>
4230               <term><varname>transdate</varname></term>
4231
4232               <listitem>
4233                 <para>Lieferscheindatum</para>
4234               </listitem>
4235             </varlistentry>
4236           </variablelist>
4237
4238           <para>Für jede Position eines Lieferscheines gibt es ein Unterarray
4239           mit den Informationen darüber, von welchem Lager und Lagerplatz aus
4240           die Waren verschickt wurden (Verkaufslieferscheine) bzw. auf welchen
4241           Lagerplatz sie eingelagert wurden. Diese müssen mittels einer
4242           <function>foreach</function>-Schleife ausgegeben werden. Diese
4243           Variablen sind:</para>
4244
4245           <variablelist>
4246             <varlistentry>
4247               <term><varname>si_bin</varname></term>
4248
4249               <listitem>
4250                 <para>Lagerplatz</para>
4251               </listitem>
4252             </varlistentry>
4253
4254             <varlistentry>
4255               <term><varname>si_chargenumber</varname></term>
4256
4257               <listitem>
4258                 <para>Chargennummer</para>
4259               </listitem>
4260             </varlistentry>
4261
4262             <varlistentry>
4263               <term><varname>si_bestbefore</varname></term>
4264
4265               <listitem>
4266                 <para>Mindesthaltbarkeit</para>
4267               </listitem>
4268             </varlistentry>
4269
4270             <varlistentry>
4271               <term><varname>si_number</varname></term>
4272
4273               <listitem>
4274                 <para>Artikelnummer</para>
4275               </listitem>
4276             </varlistentry>
4277
4278             <varlistentry>
4279               <term><varname>si_qty</varname></term>
4280
4281               <listitem>
4282                 <para>Anzahl bzw. Menge</para>
4283               </listitem>
4284             </varlistentry>
4285
4286             <varlistentry>
4287               <term><varname>si_runningnumber</varname></term>
4288
4289               <listitem>
4290                 <para>Positionsnummer (1, 2, 3 etc)</para>
4291               </listitem>
4292             </varlistentry>
4293
4294             <varlistentry>
4295               <term><varname>si_unit</varname></term>
4296
4297               <listitem>
4298                 <para>Einheit</para>
4299               </listitem>
4300             </varlistentry>
4301
4302             <varlistentry>
4303               <term><varname>si_warehouse</varname></term>
4304
4305               <listitem>
4306                 <para>Lager</para>
4307               </listitem>
4308             </varlistentry>
4309           </variablelist>
4310         </sect3>
4311
4312         <sect3 id="dokumentenvorlagen-und-variablen.andere-vorlagen-statement">
4313           <title>Variablen für Sammelrechnung</title>
4314
4315           <variablelist>
4316             <varlistentry>
4317               <term><varname>c0total</varname></term>
4318
4319               <listitem>
4320                 <para>Gesamtbetrag aller Rechnungen mit Fälligkeit &lt; 30
4321                 Tage</para>
4322               </listitem>
4323             </varlistentry>
4324
4325             <varlistentry>
4326               <term><varname>c30total</varname></term>
4327
4328               <listitem>
4329                 <para>Gesamtbetrag aller Rechnungen mit Fälligkeit &gt;= 30
4330                 und &lt; 60 Tage</para>
4331               </listitem>
4332             </varlistentry>
4333
4334             <varlistentry>
4335               <term><varname>c60total</varname></term>
4336
4337               <listitem>
4338                 <para>Gesamtbetrag aller Rechnungen mit Fälligkeit &gt;= 60
4339                 und &lt; 90 Tage</para>
4340               </listitem>
4341             </varlistentry>
4342
4343             <varlistentry>
4344               <term><varname>c90total</varname></term>
4345
4346               <listitem>
4347                 <para>Gesamtbetrag aller Rechnungen mit Fälligkeit &gt;= 90
4348                 Tage</para>
4349               </listitem>
4350             </varlistentry>
4351
4352             <varlistentry>
4353               <term><varname>total</varname></term>
4354
4355               <listitem>
4356                 <para>Gesamtbetrag aller Rechnungen</para>
4357               </listitem>
4358             </varlistentry>
4359           </variablelist>
4360
4361           <para>Variablen für jede Rechnungsposition in Sammelrechnung:</para>
4362
4363           <variablelist>
4364             <varlistentry>
4365               <term><varname>invnumber</varname></term>
4366
4367               <listitem>
4368                 <para>Rechnungsnummer</para>
4369               </listitem>
4370             </varlistentry>
4371
4372             <varlistentry>
4373               <term><varname>invdate</varname></term>
4374
4375               <listitem>
4376                 <para>Rechnungsdatum</para>
4377               </listitem>
4378             </varlistentry>
4379
4380             <varlistentry>
4381               <term><varname>duedate</varname></term>
4382
4383               <listitem>
4384                 <para>Fälligkeitsdatum</para>
4385               </listitem>
4386             </varlistentry>
4387
4388             <varlistentry>
4389               <term><varname>amount</varname></term>
4390
4391               <listitem>
4392                 <para>Summe der Rechnung</para>
4393               </listitem>
4394             </varlistentry>
4395
4396             <varlistentry>
4397               <term><varname>open</varname></term>
4398
4399               <listitem>
4400                 <para>Noch offener Betrag der Rechnung</para>
4401               </listitem>
4402             </varlistentry>
4403
4404             <varlistentry>
4405               <term><varname>c0</varname></term>
4406
4407               <listitem>
4408                 <para>Noch offener Rechnungsbetrag mit Fälligkeit &lt; 30
4409                 Tage</para>
4410               </listitem>
4411             </varlistentry>
4412
4413             <varlistentry>
4414               <term><varname>c30</varname></term>
4415
4416               <listitem>
4417                 <para>Noch offener Rechnungsbetrag mit Fälligkeit &gt;= 30 und
4418                 &lt; 60 Tage</para>
4419               </listitem>
4420             </varlistentry>
4421
4422             <varlistentry>
4423               <term><varname>c60</varname></term>
4424
4425               <listitem>
4426                 <para>Noch offener Rechnungsbetrag mit Fälligkeit &gt;= 60 und
4427                 &lt; 90 Tage</para>
4428               </listitem>
4429             </varlistentry>
4430
4431             <varlistentry>
4432               <term><varname>c90</varname></term>
4433
4434               <listitem>
4435                 <para>Noch offener Rechnungsbetrag mit Fälligkeit &gt;= 90
4436                 Tage</para>
4437               </listitem>
4438             </varlistentry>
4439           </variablelist>
4440         </sect3>
4441       </sect2>
4442
4443       <sect2 id="dokumentenvorlagen-und-variablen.bloecke">
4444         <title>Blöcke, bedingte Anweisungen und Schleifen</title>
4445
4446         <sect3 id="dokumentenvorlagen-und-variablen.bloecke.einfuehrung">
4447           <title>Einfürhung</title>
4448
4449           <para>Der Parser kennt neben den Variablen einige weitere
4450           Konstrukte, die gesondert behandelt werden. Diese sind wie
4451           Variablennamen in spezieller Weise markiert:
4452           <command>&lt;%anweisung%&gt; ... &lt;%end%&gt;</command></para>
4453
4454           <para>Anmerkung zum <command>&lt;%end%&gt;</command>: Der besseren
4455           Verständlichkeit halber kann man nach dem <command>end</command>
4456           noch beliebig weitere Wörter schreiben, um so zu markieren, welche
4457           Anweisung (z.B. <command>if</command> oder
4458           <command>foreach</command>) damit abgeschlossen wird.</para>
4459
4460           <para>Beispiel: Lautet der Beginn eines Blockes z.B.
4461           <command>&lt;%if type == "sales_quotation"%&gt;</command>, so könnte
4462           er mit <command>&lt;%end%&gt;</command> genauso abgeschlossen werden
4463           wie mit <command>&lt;%end if%&gt;</command> oder auch
4464           <command>&lt;%end type == "sales_quotation"%&gt;</command>.</para>
4465         </sect3>
4466
4467         <sect3 id="dokumentenvorlagen-und-variablen.bloecke.if">
4468           <title>Der if-Block</title>
4469
4470           <programlisting>&lt;%if variablenname%&gt;
4471 ...
4472 &lt;%end%&gt;</programlisting>
4473
4474           <para>Eine normale "if-then"-Bedingung. Die Zeilen zwischen dem "if"
4475           und dem "end" werden nur ausgegeben, wenn die Variable
4476           <varname>variablenname</varname> gesetzt und ungleich 0 ist.</para>
4477
4478           <para>Handelt es sich bei der benannten Variable um ein Array, also um einen Variablennamen, über den man mit
4479           <command>&lt;%foreach variablenname%&gt;</command> iteriert, so wird mit diesem Konstrukt darauf getestet, ob das Array Elemente
4480           enthält. Somit würde im folgenden Beispiel nur dann eine Liste von Zahlungseingängen samt ihrer Überschrift "Zahlungseingänge"
4481           ausgegeben, wenn tatsächlich welche getätigt wurden:</para>
4482
4483           <programlisting>&lt;%if payment%&gt;
4484 Zahlungseingänge:
4485  &lt;%foreach payment%&gt;
4486    Am &lt;%paymentdate%&gt;: &lt;%payment%&gt; €
4487  &lt;%end foreach%&gt;
4488 &lt;%end if%&gt;</programlisting>
4489
4490           <para>Die Bedingung kann auch negiert werden, indem das Wort
4491           <function>not</function> nach dem <filename>if</filename> verwendet
4492           wird. Beispiel:</para>
4493
4494           <programlisting>&lt;%if not cp_greeting%&gt;
4495 ...
4496 &lt;%end%&gt;</programlisting>
4497
4498           <para>Zusätzlich zu dem einfachen Test, ob eine Variable gesetzt ist
4499           oder nicht, bietet dieser Block auch die Möglichkeit, den Inhalt
4500           einer Variablen mit einer festen Zeichenkette oder einer anderen
4501           Variablen zu vergleichen. Ob der Vergleich mit einer Zeichenkette
4502           oder einer anderen Variablen vorgenommen wird, hängt davon ab, ob
4503           die rechte Seite des Vergleichsoperators in Anführungszeichen
4504           gesetzt wird (Vergleich mit Zeichenkette) oder nicht (Vergleich mit
4505           anderer Variablen). Zwei Beispiele, die beide Vergleiche
4506           zeigen:</para>
4507
4508           <programlisting>&lt;%if var1 == "Wert"%&gt;</programlisting>
4509
4510           <para>Testet die Variable <varname>var1</varname> auf
4511           übereinstimmung mit der Zeichenkette <constant>Wert</constant>.
4512           Mittels <function>!=</function> anstelle von <function>==</function>
4513           würde auf Ungleichheit getestet.</para>
4514
4515           <programlisting>&lt;%if var1 == var2%&gt;</programlisting>
4516
4517           <para>Testet die Variable <varname>var1</varname> auf
4518           übereinstimmung mit der Variablen <varname>var2</varname>. Mittel
4519           <function>!=</function> anstelle von <function>==</function> würde
4520           auf Ungleichheit getestet.</para>
4521
4522           <para>Erfahrere Benutzer können neben der Tests auf (Un-)Gleichheit
4523           auch Tests auf übereinstimmung mit regulären Ausdrücken ohne
4524           Berücksichtung der Groß- und Kleinschreibung durchführen. Dazu dient
4525           dieselbe Syntax wie oben nur mit <function>=~</function> und
4526           <function>!~</function> als Vergleichsoperatoren.</para>
4527
4528           <para>Beispiel für einen Test, ob die Variable
4529           <varname>intnotes</varname> (interne Bemerkungen) das Wort
4530           <constant>schwierig</constant> enthält:</para>
4531
4532           <programlisting>&lt;%if intnotes =~ "schwierig"%&gt;</programlisting>
4533         </sect3>
4534
4535         <sect3 id="dokumentenvorlagen-und-variablen.bloecke.foreach">
4536           <title>Der foreach-Block</title>
4537
4538           <programlisting>&lt;%foreach variablenname%&gt;
4539 ...
4540 &lt;%end%&gt;</programlisting>
4541
4542           <para>Fügt die Zeilen zwischen den beiden Anweisungen so oft ein,
4543           wie das Perl-Array der Variablen <varname>variablenname</varname>
4544           Elemente enthät. Dieses Konstrukt wird zur Ausgabe der einzelnen
4545           Posten einer Rechnung / eines Angebots sowie zur Ausgabe der Steuern
4546           benutzt. In jedem Durchlauf werden die <link
4547           linkend="dokumentenvorlagen-und-variablen.invoice-posten">zeilenbezogenen
4548           Variablen</link> jeweils auf den Wert für die aktuelle Position
4549           gesetzt.</para>
4550
4551           <para>Die Syntax sieht normalerweise wie folgt aus:</para>
4552
4553           <programlisting>&lt;%foreach number%&gt;
4554 Position: &lt;%runningnumber%&gt;
4555 Anzahl: &lt;%qty%&gt;
4556 Artikelnummer: &lt;%number%&gt;
4557 Beschreibung: &lt;%description%&gt;
4558 ...
4559 &lt;%end%&gt;</programlisting>
4560
4561           <para>Besonderheit in OpenDocument-Vorlagen: Tritt ein
4562           <function>&lt;%foreach%&gt;</function>-Block innerhalb einer
4563           Tabellenzelle auf, so wird die komplette Tabellenzeile so oft
4564           wiederholt wie notwendig. Tritt er außerhalb auf, so wird nur der
4565           Inhalt zwischen <function>&lt;%foreach%&gt;</function> und
4566           <function>&lt;%end%&gt;</function> wiederholt, nicht aber die
4567           komplette Zeile, in der er steht.</para>
4568         </sect3>
4569       </sect2>
4570
4571       <sect2 id="dokumentenvorlagen-und-variablen.markup">
4572         <title>Markup-Code zur Textformatierung innerhalb von
4573         Formularen</title>
4574
4575         <para>Wenn der Benutzer innhalb von Formularen in kivitendo Text
4576         anders formatiert haben möchte, so ist dies begrenzt möglich.
4577         kivitendo unterstützt die Textformatierung mit HTML-ähnlichen Tags.
4578         Der Benutzer kann z.B. bei der Artikelbeschreibung auf einer Rechnung
4579         Teile des Texts zwischen Start- und Endtags setzen. Dieser Teil wird
4580         dann automatisch in Anweisungen für das ausgewählte Vorlagenformat
4581         (HTML oder PDF über LaTeX) umgesetzt.</para>
4582
4583         <para>Die unterstützen Formatierungen sind:</para>
4584
4585         <variablelist>
4586           <varlistentry>
4587             <term>&lt;b&gt;Text&lt;/b&gt;</term>
4588
4589             <listitem>
4590               <para>Text wird in Fettdruck gesetzt.</para>
4591             </listitem>
4592           </varlistentry>
4593
4594           <varlistentry>
4595             <term>&lt;i&gt;Text&lt;/i&gt;</term>
4596
4597             <listitem>
4598               <para>Text wird kursiv gesetzt.</para>
4599             </listitem>
4600           </varlistentry>
4601
4602           <varlistentry>
4603             <term>&lt;u&gt;Text&lt;/u&gt;</term>
4604
4605             <listitem>
4606               <para>Text wird unterstrichen.</para>
4607             </listitem>
4608           </varlistentry>
4609
4610           <varlistentry>
4611             <term>&lt;s&gt;Text&lt;/s&gt;</term>
4612
4613             <listitem>
4614               <para>Text wird durchgestrichen. Diese Formatierung ist nicht
4615               bei der Ausgabe als PDF über LaTeX verfügbar.</para>
4616             </listitem>
4617           </varlistentry>
4618
4619           <varlistentry>
4620             <term>&lt;bullet&gt;</term>
4621
4622             <listitem>
4623               <para>Erzeugt einen ausgefüllten Kreis für Aufzählungen (siehe
4624               unten).</para>
4625             </listitem>
4626           </varlistentry>
4627         </variablelist>
4628
4629         <para>Der Befehl <command>&lt;bullet&gt;</command> funktioniert
4630         momentan auch nur in Latex-Vorlagen.</para>
4631       </sect2>
4632     </sect1>
4633
4634     <sect1 id="excel-templates">
4635       <title>Excel-Vorlagen</title>
4636
4637       <sect2 id="excel-templates.summary">
4638         <title>Zusammenfassung</title>
4639
4640         <para>Dieses Dokument beschreibt den Mechanismus, mit dem
4641         Exceltemplates abgearbeitet werden, und die Einschränkungen, die damit
4642         einhergehen.</para>
4643       </sect2>
4644
4645       <sect2 id="excel-templates.usage">
4646         <title>Bedienung</title>
4647
4648         <para>Der Excel Mechanismus muss in der Konfigurationsdatei aktiviert
4649         werden. Die Konfigurationsoption heißt <varname>excel_templates =
4650         1</varname> im Abschnitt <varname>[print_templates]</varname>.</para>
4651
4652         <para>Eine Excelvorlage kann dann unter dem Namen einer beliebigen
4653         anderen Vorlage mit der Endung <filename>.xls</filename> gespeichert
4654         werden. In den normalen Verkaufsmasken taucht nun
4655         <constant>Excel</constant> als auswählbares Format auf und kann von da
4656         an wie LaTeX- oder OpenOffice-Vorlagen benutzt werden.</para>
4657
4658         <para>Der Sonderfall der Angebote aus der Kundenmaske ist ebenfalls
4659         eine Angebotsvorlage und wird unter dem internen Namen der Angebote
4660         <filename>sales_quotation.xls</filename> gespeichert.</para>
4661       </sect2>
4662
4663       <sect2 id="excel-templates.syntax">
4664         <title>Variablensyntax</title>
4665
4666         <para>Einfache Syntax:
4667         <command>&lt;&lt;varname&gt;&gt;</command></para>
4668
4669         <para>Dabei sind <constant>&lt;&lt;</constant> und
4670         <constant>&gt;&gt;</constant> die Delimiter. Da Excel auf festen
4671         Breiten besteht, kann der Tag künstlich verlängert werden, indem
4672         weitere <constant>&lt;</constant> oder <constant>&gt;</constant>
4673         eingefügt werden. Der Tag muss nicht symmetrisch sein.
4674         Beispiel:</para>
4675
4676         <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>
4677
4678         <para>Um die Limitierung der festen Breite zu reduzieren, können
4679         weitere Variablen in einem Block interpoliert werden. Whitespace wird
4680         dazwishen dann erhalten. Beispiel:</para>
4681
4682         <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>
4683
4684         <para>Die Variablen werden interpoliert, und linksbündig mit
4685         Leerzeichen auf die gewünschte Länge aufgefüllt. Ist der String zu
4686         lang, werden überzählige Zeichen abgeschnitten.</para>
4687
4688         <para>Es ist ausserdem möglich, Daten rechtsbündig darzustellen, wenn
4689         der Block mit einem Leerzeichen anfängt. Beispiel:</para>
4690
4691         <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>
4692
4693         <para>Dies würde rechtsbündig triggern. Wenn bei rechtsbündiger
4694         Ausrichtung Text abgeschnitten werden muss, wird er vom linken Ende
4695         entfernt.</para>
4696       </sect2>
4697
4698       <sect2 id="excel-templates.limitations">
4699         <title>Einschränkungen</title>
4700
4701         <para>Das Excelformat bis 2002 ist ein binäres Format, und kann nicht
4702         mit vertretbarem Aufwand editiert werden. Der Templatemechanismus
4703         beschränkt sich daher darauf, Textstellen exakt durch einen anderen
4704         Text zu ersetzen.</para>
4705
4706         <para>Aus dem gleichen Grund sind die Kontrolllstrukturen
4707         <command>&lt;%if%&gt;</command> und
4708         <command>&lt;%foreach%&gt;</command> nicht vorhanden. Der Delimiter
4709         <constant>&lt;% %&gt;</constant> kommt in den Headerinformationen
4710         evtl. vor. Deshalb wurde auf den sichereren Delimiter
4711         <constant>&lt;&lt;</constant> und <constant>&gt;&gt;</constant>
4712         gewechselt.</para>
4713       </sect2>
4714     </sect1>
4715   </chapter>
4716
4717   <chapter>
4718     <title>Entwicklerdokumentation</title>
4719
4720     <sect1 id="devel.globals" xreflabel="Globale Variablen">
4721       <title>Globale Variablen</title>
4722
4723       <sect2>
4724         <title>Wie sehen globale Variablen in Perl aus?</title>
4725
4726         <para>Globale Variablen liegen in einem speziellen namespace namens
4727         "main", der von überall erreichbar ist. Darüber hinaus sind bareword
4728         globs global und die meisten speziellen Variablen sind...
4729         speziell.</para>
4730
4731         <para>Daraus ergeben sich folgende Formen:</para>
4732
4733         <variablelist>
4734           <varlistentry>
4735             <term><literal>$main::form</literal></term>
4736
4737             <listitem>
4738               <para>expliziter Namespace "main"</para>
4739             </listitem>
4740           </varlistentry>
4741
4742           <varlistentry>
4743             <term><literal>$::form</literal></term>
4744
4745             <listitem>
4746               <para>impliziter Namespace "main"</para>
4747             </listitem>
4748           </varlistentry>
4749
4750           <varlistentry>
4751             <term><literal>open FILE, "file.txt"</literal></term>
4752
4753             <listitem>
4754               <para><varname>FILE</varname> ist global</para>
4755             </listitem>
4756           </varlistentry>
4757
4758           <varlistentry>
4759             <term><literal>$_</literal></term>
4760
4761             <listitem>
4762               <para>speziell</para>
4763             </listitem>
4764           </varlistentry>
4765         </variablelist>
4766
4767         <para>Im Gegensatz zu <productname>PHP</productname> gibt es kein
4768         Schlüsselwort wie "<function>global</function>", mit dem man
4769         importieren kann. <function>my</function>, <function>our</function>
4770         und <function>local</function> machen was anderes.</para>
4771
4772         <variablelist>
4773           <varlistentry>
4774             <term><literal>my $form</literal></term>
4775
4776             <listitem>
4777               <para>lexikalische Variable, gültig bis zum Ende des
4778               Scopes</para>
4779             </listitem>
4780           </varlistentry>
4781
4782           <varlistentry>
4783             <term><literal>our $form</literal></term>
4784
4785             <listitem>
4786               <para><varname>$form</varname> referenziert ab hier
4787               <varname>$PACKAGE::form</varname>.</para>
4788             </listitem>
4789           </varlistentry>
4790
4791           <varlistentry>
4792             <term><literal>local $form</literal></term>
4793
4794             <listitem>
4795               <para>Alle Änderungen an <varname>$form</varname> werden am Ende
4796               des scopes zurückgesetzt</para>
4797             </listitem>
4798           </varlistentry>
4799         </variablelist>
4800       </sect2>
4801
4802       <sect2>
4803         <title>Warum sind globale Variablen ein Problem?</title>
4804
4805         <para>Das erste Problem ist <productname>FCGI</productname>.</para>
4806
4807         <para><productname>SQL-Ledger</productname> hat fast alles im globalen
4808         namespace abgelegt, und erwartet, dass es da auch wiederzufinden ist.
4809         Unter <productname>FCGI</productname> müssen diese Sachen aber wieder
4810         aufgeräumt werden, damit sie nicht in den nächsten Request kommen.
4811         Einige Sachen wiederum sollen nicht gelöscht werden, wie zum Beispiel
4812         Datenbankverbindungen, weil die sehr lange zum Initialisieren
4813         brauchen.</para>
4814
4815         <para>Das zweite Problem ist <function>strict</function>. Unter
4816         <function>strict</function> werden alle Variablen die nicht explizit
4817         mit <function>Package</function>, <function>my</function> oder
4818         <function>our</function> angegeben werden als Tippfehler angemarkert,
4819         dies hat, seit der Einführung, u.a. schon so manche langwierige
4820         Bug-Suche verkürzt. Da globale Variablen aber implizit mit Package
4821         angegeben werden, werden die nicht geprüft, und somit kann sich
4822         schnell ein Tippfehler einschleichen.</para>
4823       </sect2>
4824
4825       <sect2>
4826         <title>Kanonische globale Variablen</title>
4827
4828         <para>Um dieses Problem im Griff zu halten gibt es einige wenige
4829         globale Variablen, die kanonisch sind, d.h. sie haben bestimmte
4830         vorgegebenen Eigenschaften, und alles andere sollte anderweitig
4831         umhergereicht werden.</para>
4832
4833         <para>Diese Variablen sind im Moment die folgenden neun:</para>
4834
4835         <itemizedlist>
4836           <listitem>
4837             <para><varname>$::form</varname></para>
4838           </listitem>
4839
4840           <listitem>
4841             <para><varname>%::myconfig</varname></para>
4842           </listitem>
4843
4844           <listitem>
4845             <para><varname>$::locale</varname></para>
4846           </listitem>
4847
4848           <listitem>
4849             <para><varname>$::lxdebug</varname></para>
4850           </listitem>
4851
4852           <listitem>
4853             <para><varname>$::auth</varname></para>
4854           </listitem>
4855
4856           <listitem>
4857             <para><varname>$::lx_office_conf</varname></para>
4858           </listitem>
4859
4860           <listitem>
4861             <para><varname>$::instance_conf</varname></para>
4862           </listitem>
4863
4864           <listitem>
4865             <para><varname>$::dispatcher</varname></para>
4866           </listitem>
4867
4868           <listitem>
4869             <para><varname>$::request</varname></para>
4870           </listitem>
4871         </itemizedlist>
4872
4873         <para>Damit diese nicht erneut als Müllhalde missbraucht werden, im
4874         Folgenden eine kurze Erläuterung der bestimmten vorgegebenen
4875         Eigenschaften (Konventionen):</para>
4876
4877         <sect3>
4878           <title>$::form</title>
4879
4880           <itemizedlist>
4881             <listitem>
4882               <para>Ist ein Objekt der Klasse
4883               "<classname>Form</classname>"</para>
4884             </listitem>
4885
4886             <listitem>
4887               <para>Wird nach jedem Request gelöscht</para>
4888             </listitem>
4889
4890             <listitem>
4891               <para>Muss auch in Tests und Konsolenscripts vorhanden
4892               sein.</para>
4893             </listitem>
4894
4895             <listitem>
4896               <para>Enthält am Anfang eines Requests die Requestparameter vom
4897               User</para>
4898             </listitem>
4899
4900             <listitem>
4901               <para>Kann zwar intern über Requestgrenzen ein Datenbankhandle
4902               cachen, das wird aber momentan absichtlich zerstört</para>
4903             </listitem>
4904           </itemizedlist>
4905
4906           <para><varname>$::form</varname> wurde unter <productname>SQL
4907           Ledger</productname> als Gottobjekt für alles misbraucht. Sämtliche
4908           alten Funktionen unter SL/ mutieren <varname>$::form</varname>, das
4909           heißt, alles was einem lieb ist (alle Variablen die einem ans Herz
4910           gewachsen sind), sollte man vor einem Aufruf (!) von zum Beispiel
4911           <function>IS-&gt;retrieve_customer()</function> in Sicherheit
4912           bringen.</para>
4913
4914           <para>Z.B. das vom Benutzer eingestellte Zahlenformat, bevor man
4915           Berechnung in einem bestimmten Format durchführt (SL/Form.pm Zeile
4916           3552, Stand version 2.7beta), um dies hinterher wieder auf den
4917           richtigen Wert zu setzen:</para>
4918
4919           <programlisting>  my $saved_numberformat    = $::myconfig{numberformat};
4920   $::myconfig{numberformat} = $numberformat;
4921   # (...) div Berechnungen
4922   $::myconfig{numberformat} = $saved_numberformat;</programlisting>
4923
4924           <para>Das Objekt der Klasse Form hat leider im Moment noch viele
4925           zentrale Funktionen die vom internen Zustand abhängen, deshalb bitte
4926           nie einfach zerstören oder überschreiben (zumindestens nicht kurz
4927           vor einem Release oder in Absprache über bspw. die devel-Liste ;-).
4928           Es geht ziemlich sicher etwas kaputt.</para>
4929
4930           <para><varname>$::form</varname> ist gleichzeitig der Standard Scope
4931           in den <productname>Template::Toolkit</productname> Templates
4932           außerhalb der Controller: der Ausdruck <function>[% var
4933           %]</function> greift auf <varname>$::form-&gt;{var}</varname> zu.
4934           Unter Controllern ist der Standard Scope anders, da lautet der
4935           Zugriff <function>[% FORM.var %]</function>. In Druckvorlagen sind
4936           normale Variablen ebenfall im <varname>$::form</varname> Scope, d.h.
4937           <function>&lt;%var%&gt;</function> zeigt auf
4938           <varname>$::form-&gt;{var}</varname>. Nochmal von der anderen Seite
4939           erläutert, innerhalb von (Web-)Templates sieht man häufiger solche
4940           Konstrukte:</para>
4941
4942           <programlisting>[%- IF business %]
4943 # (... Zeig die Auswahlliste Kunden-/Lieferantentyp an)
4944 [%- END %]</programlisting>
4945
4946           <para>Entweder wird hier dann $::form-&gt;{business} ausgewertet
4947           oder aber der Funktion
4948           <function>$form-&gt;parse_html_template</function> wird explizit
4949           noch ein zusätzlicher Hash übergeben, der dann auch in den
4950           (Web-)Templates zu Verfügung steht, bspw. so:</para>
4951
4952           <programlisting>$form-&gt;parse_html_template("is/form_header", \%TMPL_VAR);</programlisting>
4953
4954           <para>Innerhalb von Schleifen wird
4955           <varname>$::form-&gt;{TEMPLATE_ARRAYS}{var}[$index]</varname>
4956           bevorzugt, wenn vorhanden. Ein Beispiel findet sich in SL/DO.pm,
4957           welches über alle Positionen eines Lieferscheins in Schleife
4958           läuft:</para>
4959
4960           <programlisting>for $i (1 .. $form-&gt;{rowcount}) {
4961   # ...
4962   push @{ $form-&gt;{TEMPLATE_ARRAYS}{runningnumber} },   $position;
4963   push @{ $form-&gt;{TEMPLATE_ARRAYS}{number} },          $form-&gt;{"partnumber_$i"};
4964   push @{ $form-&gt;{TEMPLATE_ARRAYS}{description} },     $form-&gt;{"description_$i"};
4965   # ...
4966 }</programlisting>
4967         </sect3>
4968
4969         <sect3>
4970           <title>%::myconfig</title>
4971
4972           <itemizedlist>
4973             <listitem>
4974               <para>Das einzige Hash unter den globalen Variablen</para>
4975             </listitem>
4976
4977             <listitem>
4978               <para>Wird spätestens benötigt wenn auf die Datenbank
4979               zugegriffen wird</para>
4980             </listitem>
4981
4982             <listitem>
4983               <para>Wird bei jedem Request neu erstellt.</para>
4984             </listitem>
4985
4986             <listitem>
4987               <para>Enthält die Userdaten des aktuellen Logins</para>
4988             </listitem>
4989
4990             <listitem>
4991               <para>Sollte nicht ohne Filterung irgendwo gedumpt werden oder
4992               extern serialisiert werden, weil da auch der Datenbankzugriff
4993               für diesen user drinsteht.</para>
4994             </listitem>
4995
4996             <listitem>
4997               <para>Enthält unter anderem Listenbegrenzung vclimit,
4998               Datumsformat dateformat und Nummernformat numberformat</para>
4999             </listitem>
5000
5001             <listitem>
5002               <para>Enthält Datenbankzugriffinformationen</para>
5003             </listitem>
5004           </itemizedlist>
5005
5006           <para><varname>%::myconfig</varname> ist im Moment der Ersatz für
5007           ein Userobjekt. Die meisten Funktionen, die etwas anhand des
5008           aktuellen Users entscheiden müssen, befragen
5009           <varname>%::myconfig</varname>. Innerhalb der Anwendungen sind dies
5010           überwiegend die Daten, die sich unter <guimenu>Programm</guimenu>
5011           -&gt; <guimenuitem>Einstellungen</guimenuitem> befinden, bzw. die
5012           Informationen über den Benutzer die über die
5013           Administrator-Schnittstelle (admin.pl) eingegeben wurden.</para>
5014         </sect3>
5015
5016         <sect3>
5017           <title>$::locale</title>
5018
5019           <itemizedlist>
5020             <listitem>
5021               <para>Objekt der Klasse "Locale"</para>
5022             </listitem>
5023
5024             <listitem>
5025               <para>Wird pro Request erstellt</para>
5026             </listitem>
5027
5028             <listitem>
5029               <para>Muss auch für Tests und Scripte immer verfügbar
5030               sein.</para>
5031             </listitem>
5032
5033             <listitem>
5034               <para>Cached intern über Requestgrenzen hinweg benutzte
5035               Locales</para>
5036             </listitem>
5037           </itemizedlist>
5038
5039           <para>Lokalisierung für den aktuellen User. Alle Übersetzungen,
5040           Zahlen- und Datumsformatierungen laufen über dieses Objekt.</para>
5041         </sect3>
5042
5043         <sect3>
5044           <title>$::lxdebug</title>
5045
5046           <itemizedlist>
5047             <listitem>
5048               <para>Objekt der Klasse "LXDebug"</para>
5049             </listitem>
5050
5051             <listitem>
5052               <para>Wird global gecached</para>
5053             </listitem>
5054
5055             <listitem>
5056               <para>Muss immer verfügbar sein, in nahezu allen
5057               Funktionen</para>
5058             </listitem>
5059           </itemizedlist>
5060
5061           <para><varname>$::lxdebug</varname> stellt Debuggingfunktionen
5062           bereit, wie "<function>enter_sub</function>" und
5063           "<function>leave_sub</function>", mit denen in den alten Modulen ein
5064           brauchbares Tracing gebaut ist, "<function>log_time</function>", mit
5065           der man die Wallclockzeit seit Requeststart loggen kann, sowie
5066           "<function>message</function>" und "<function>dump</function>" mit
5067           denen man flott Informationen ins Log (tmp/kivitendo-debug.log)
5068           packen kann.</para>
5069
5070           <para>Beispielsweise so:</para>
5071
5072           <programlisting>$main::lxdebug-&gt;message(0, 'Meine Konfig:' . Dumper (%::myconfig));
5073 $main::lxdebug-&gt;message(0, 'Wer bin ich? Kunde oder Lieferant:' . $form-&gt;{vc});</programlisting>
5074         </sect3>
5075
5076         <sect3>
5077           <title>$::auth</title>
5078
5079           <itemizedlist>
5080             <listitem>
5081               <para>Objekt der Klasse "SL::Auth"</para>
5082             </listitem>
5083
5084             <listitem>
5085               <para>Wird global gecached</para>
5086             </listitem>
5087
5088             <listitem>
5089               <para>Hat eine permanente DB Verbindung zur Authdatenbank</para>
5090             </listitem>
5091
5092             <listitem>
5093               <para>Wird nach jedem Request resettet.</para>
5094             </listitem>
5095           </itemizedlist>
5096
5097           <para><varname>$::auth</varname> stellt Funktionen bereit um die
5098           Rechte des aktuellen Users abzufragen. Obwohl diese Informationen
5099           vom aktuellen User abhängen wird das Objekt aus
5100           Geschwindigkeitsgründen nur einmal angelegt und dann nach jedem
5101           Request kurz resettet.</para>
5102         </sect3>
5103
5104         <sect3>
5105           <title>$::lx_office_conf</title>
5106
5107           <itemizedlist>
5108             <listitem>
5109               <para>Objekt der Klasse
5110               "<classname>SL::LxOfficeConf</classname>"</para>
5111             </listitem>
5112
5113             <listitem>
5114               <para>Global gecached</para>
5115             </listitem>
5116
5117             <listitem>
5118               <para>Repräsentation der
5119               <filename>config/kivitendo.conf[.default]</filename>-Dateien</para>
5120             </listitem>
5121           </itemizedlist>
5122
5123           <para>Globale Konfiguration. Configdateien werden zum Start gelesen
5124           und danach nicht mehr angefasst. Es ist derzeit nicht geplant, dass
5125           das Programm die Konfiguration ändern kann oder sollte.</para>
5126
5127           <para>Beispielsweise ist über den Konfigurationseintrag [debug] die
5128           Debug- und Trace-Log-Datei wie folgt konfiguriert und
5129           verfügbar:</para>
5130
5131           <programlisting>[debug]
5132 file = /tmp/kivitendo-debug.log</programlisting>
5133
5134           <para>ist der Key <varname>file</varname> im Programm als
5135           <varname>$::lx_office_conf-&gt;{debug}{file}</varname>
5136           erreichbar.</para>
5137
5138           <warning>
5139             <para>Zugriff auf die Konfiguration erfolgt im Moment über
5140             Hashkeys, sind also nicht gegen Tippfehler abgesichert.</para>
5141           </warning>
5142         </sect3>
5143
5144         <sect3>
5145           <title>$::instance_conf</title>
5146
5147           <itemizedlist>
5148             <listitem>
5149               <para>Objekt der Klasse
5150               "<classname>SL::InstanceConfiguration</classname>"</para>
5151             </listitem>
5152
5153             <listitem>
5154               <para>wird pro Request neu erstellt</para>
5155             </listitem>
5156           </itemizedlist>
5157
5158           <para>Funktioniert wie <varname>$::lx_office_conf</varname>,
5159           speichert aber Daten die von der Instanz abhängig sind. Eine Instanz
5160           ist hier eine Mandantendatenbank. Beispielsweise überprüft
5161           <programlisting>$::instance_conf-&gt;get_inventory_system eq 'perpetual'</programlisting>
5162           ob die berüchtigte Bestandsmethode zur Anwendung kommt.</para>
5163         </sect3>
5164
5165         <sect3>
5166           <title>$::dispatcher</title>
5167
5168           <itemizedlist>
5169             <listitem>
5170               <para>Objekt der Klasse
5171               "<varname>SL::Dispatcher</varname>"</para>
5172             </listitem>
5173
5174             <listitem>
5175               <para>wird pro Serverprozess erstellt.</para>
5176             </listitem>
5177
5178             <listitem>
5179               <para>enthält Informationen über die technische Verbindung zum
5180               Server</para>
5181             </listitem>
5182           </itemizedlist>
5183
5184           <para>Der dritte Punkt ist auch der einzige Grund warum das Objekt
5185           global gespeichert wird. Wird vermutlich irgendwann in einem anderen
5186           Objekt untergebracht.</para>
5187         </sect3>
5188
5189         <sect3>
5190           <title>$::request</title>
5191
5192           <itemizedlist>
5193             <listitem>
5194               <para>Hashref (evtl später Objekt)</para>
5195             </listitem>
5196
5197             <listitem>
5198               <para>Wird pro Request neu initialisiert.</para>
5199             </listitem>
5200
5201             <listitem>
5202               <para>Keine Unterstruktur garantiert.</para>
5203             </listitem>
5204           </itemizedlist>
5205
5206           <para><varname>$::request</varname> ist ein generischer Platz um
5207           Daten "für den aktuellen Request" abzulegen. Sollte nicht für action
5208           at a distance benutzt werden, sondern um lokales memoizing zu
5209           ermöglichen, das garantiert am Ende des Requests zerstört
5210           wird.</para>
5211
5212           <para>Vieles von dem, was im moment in <varname>$::form</varname>
5213           liegt, sollte eigentlich hier liegen. Die groben
5214           Differentialkriterien sind:</para>
5215
5216           <itemizedlist>
5217             <listitem>
5218               <para>Kommt es vom User, und soll unverändert wieder an den
5219               User? Dann <varname>$::form</varname>, steht da eh schon</para>
5220             </listitem>
5221
5222             <listitem>
5223               <para>Sind es Daten aus der Datenbank, die nur bis zum Ende des
5224               Requests gebraucht werden? Dann
5225               <varname>$::request</varname></para>
5226             </listitem>
5227
5228             <listitem>
5229               <para>Muss ich von anderen Teilen des Programms lesend drauf
5230               zugreifen? Dann <varname>$::request</varname>, aber Zugriff über
5231               Wrappermethode</para>
5232             </listitem>
5233           </itemizedlist>
5234         </sect3>
5235       </sect2>
5236
5237       <sect2>
5238         <title>Ehemalige globale Variablen</title>
5239
5240         <para>Die folgenden Variablen waren einmal im Programm, und wurden
5241         entfernt.</para>
5242
5243         <sect3>
5244           <title>$::cgi</title>
5245
5246           <itemizedlist>
5247             <listitem>
5248               <para>war nötig, weil cookie Methoden nicht als
5249               Klassenfunktionen funktionieren</para>
5250             </listitem>
5251
5252             <listitem>
5253               <para>Aufruf als Klasse erzeugt Dummyobjekt was im
5254               Klassennamespace gehalten wird und über Requestgrenzen
5255               leaked</para>
5256             </listitem>
5257
5258             <listitem>
5259               <para>liegt jetzt unter
5260               <varname>$::request-&gt;{cgi}</varname></para>
5261             </listitem>
5262           </itemizedlist>
5263         </sect3>
5264
5265         <sect3>
5266           <title>$::all_units</title>
5267
5268           <itemizedlist>
5269             <listitem>
5270               <para>war nötig, weil einige Funktionen in Schleifen zum Teil
5271               ein paar hundert mal pro Request eine Liste der Einheiten
5272               brauchen, und de als Parameter durch einen Riesenstack von
5273               Funktionen geschleift werden müssten.</para>
5274             </listitem>
5275
5276             <listitem>
5277               <para>Liegt jetzt unter
5278               <varname>$::request-&gt;{cache}{all_units}</varname></para>
5279             </listitem>
5280
5281             <listitem>
5282               <para>Wird nur in
5283               <function>AM-&gt;retrieve_all_units()</function> gesetzt oder
5284               gelesen.</para>
5285             </listitem>
5286           </itemizedlist>
5287         </sect3>
5288
5289         <sect3>
5290           <title>%::called_subs</title>
5291
5292           <itemizedlist>
5293             <listitem>
5294               <para>wurde benutzt um callsub deep recursions
5295               abzufangen.</para>
5296             </listitem>
5297
5298             <listitem>
5299               <para>Wurde entfernt, weil callsub nur einen Bruchteil der
5300               möglichen Rekursioenen darstellt, und da nie welche
5301               auftreten.</para>
5302             </listitem>
5303
5304             <listitem>
5305               <para>komplette recursion protection wurde entfernt.</para>
5306             </listitem>
5307           </itemizedlist>
5308         </sect3>
5309       </sect2>
5310     </sect1>
5311
5312     <sect1 id="devel.fcgi">
5313       <title>Entwicklung unter FastCGI</title>
5314
5315       <sect2 id="devel.fcgi.general">
5316         <title>Allgemeines</title>
5317
5318         <para>Wenn Änderungen in der Konfiguration von kivitendo gemacht
5319         werden, muss der Webserver neu gestartet werden.</para>
5320
5321         <para>Bei der Entwicklung für FastCGI ist auf ein paar Fallstricke zu
5322         achten. Dadurch, dass das Programm in einer Endlosschleife läuft,
5323         müssen folgende Aspekte beachtet werden.</para>
5324       </sect2>
5325
5326       <sect2 id="devel.fcgi.exiting">
5327         <title>Programmende und Ausnahmen</title>
5328
5329         <para>Betrifft die Funktionen <function>warn</function>,
5330         <function>die</function>, <function>exit</function>,
5331         <function>carp</function> und <function>confess</function>.</para>
5332
5333         <para>Fehler, die dass Programm normalerweise sofort beenden (fatale
5334         Fehler), werden mit dem FastCGI Dispatcher abgefangen, um das Programm
5335         am Laufen zu halten. Man kann mit <function>die</function>,
5336         <function>confess</function> oder <function>carp</function> Fehler
5337         ausgeben, die dann vom Dispatcher angezeigt werden. Die kivitendo
5338         eigene <function>$::form-</function>error()&gt; tut im Prinzip das
5339         Gleiche, mit ein paar Extraoptionen. <function>warn</function> und
5340         <function>exit</function> hingegen werden nicht abgefangen.
5341         <function>warn</function> wird direkt nach STDERR, also in Server Log
5342         eine Nachricht schreiben (sofern in der Konfiguration nicht die
5343         Warnungen in das kivitendo Log umgeleitet wurden), und
5344         <function>exit</function> wird die Ausführung beenden.</para>
5345
5346         <para>Prinzipiell ist es kein Beinbruch, wenn sich der Prozess
5347         beendet, fcgi wird ihn sofort neu starten. Allerdings sollte das die
5348         Ausnahme sein. Quintessenz: Bitte kein <function>exit</function>
5349         benutzen, alle anderen Exceptionmechanismen sind ok.</para>
5350       </sect2>
5351
5352       <sect2 id="devel.fcgi.globals">
5353         <title>Globale Variablen</title>
5354
5355         <para>Um zu vermeiden, dass Informationen von einem Request in einen
5356         anderen gelangen, müssen alle globalen Variablen vor einem Request
5357         sauber initialisiert werden. Das ist besonders wichtig im
5358         <varname>$::cgi</varname> und <varname>$::auth</varname> Objekt, weil
5359         diese nicht gelöscht werden pro Instanz, sondern persistent gehalten
5360         werden.</para>
5361
5362         <para>In <classname>SL::Dispatcher</classname> gibt es einen sauber
5363         abgetrennten Block, der alle kanonischen globalen Variablen listet und
5364         erklärt. Bitte keine anderen einführen ohne das sauber zu
5365         dokumentieren.</para>
5366
5367         <para>Datenbankverbindungen wird noch ein Guide verfasst werden, wie
5368         man sicher geht, dass man die richtige erwischt.</para>
5369       </sect2>
5370
5371       <sect2 id="devel.fcgi.performance">
5372         <title>Performance und Statistiken</title>
5373
5374         <para>Die kritischen Pfade des Programms sind die Belegmasken, und
5375         unter diesen ganz besonders die Verkaufsrechnungsmaske. Ein Aufruf der
5376         Rechnungsmaske in kivitendo 2.4.3 stable dauert auf einem Core2duo mit
5377         4GB Arbeitsspeicher und Ubuntu 9.10 eine halbe Sekunde. In der 2.6.0
5378         sind es je nach Menge der definierten Variablen 1-2s. Ab der
5379         Moose/Rose::DB Version sind es 5-6s.</para>
5380
5381         <para>Mit FastCGI ist die neuste Version auf 0,26 Sekunden selbst in
5382         den kritischen Pfaden, unter 0,15 sonst.</para>
5383       </sect2>
5384
5385       <sect2 id="devel.fcgi.known-issues">
5386         <title>Bekannte Probleme</title>
5387
5388         <sect3 id="devel.fcgi.known-issues.encoding">
5389           <title>Encoding Awareness</title>
5390
5391           <para>UTF-8 kodierte Installationen sind sehr anfällig gegen
5392           fehlerhfate Encodings unter FCGI. latin9 Installationen behandeln
5393           falsch kodierte Zeichen eher unwissend, und geben sie einfach
5394           weiter. UTF-8 verweigert bei fehlerhaften Programmpfaden kurzerhand
5395           das Ausliefern. Es wird noch daran gearbeitet, alle Fehler da zu
5396           beseitigen.</para>
5397         </sect3>
5398       </sect2>
5399     </sect1>
5400
5401     <sect1 id="db-upgrade-files" xreflabel="Datenbank-Upgradedateien">
5402       <title>SQL-Upgradedateien</title>
5403
5404       <sect2 id="db-upgrade-files.introduction"
5405              xreflabel="Einführung in die Datenbank-Upgradedateien">
5406         <title>Einführung</title>
5407
5408         <para>Der alte Mechanismus für SQL-Upgradescripte, der auf einer
5409         Versionsnummer beruht und dann in sql/Pg-upgrade nach einem Script für
5410         diese Versionsnummer sucht, schränkt sehr ein, z.B. was die parallele
5411         Entwicklung im stable- und unstable-Baum betrifft.</para>
5412
5413         <para>Dieser Mechanismus wurde für kivitendo 2.4.1 deutlich erweitert.
5414         Es werden weiterhin alle Scripte aus sql/Pg-upgrade ausgeführt.
5415         Zusätzlich gibt es aber ein zweites Verzeichnis, sql/Pg-upgrade2. In
5416         diesem Verzeichnis muss pro Datenbankupgrade eine Datei existieren,
5417         die neben den eigentlich auszuführenden SQL- oder Perl-Befehlen einige
5418         Kontrollinformationen enthält.</para>
5419
5420         <para>Neu sind die Kontrollinformationen, die Abhängigkeiten und
5421         Prioritäten definieren können werden, sodass Datenbankscripte zwar in
5422         einer sicheren Reihenfolge ausgeführt werden (z.B. darf ein "ALTER
5423         TABLE" erst ausgeführt werden, wenn die Tabelle mit "CREATE TABLE"
5424         angelegt wurde), diese Reihenfolge aber so flexibel ist, dass man
5425         keine Versionsnummern mehr braucht.</para>
5426
5427         <para>kivitendo merkt sich dabei, welches der Upgradescripte in
5428         sql/Pg-upgrade2 bereits durchgeführt wurde und führt diese nicht
5429         erneut aus. Dazu dient die Tabelle "schema_info", die bei der
5430         Anmeldung automatisch angelegt wird.</para>
5431       </sect2>
5432
5433       <sect2 id="db-upgrade-files.format"
5434              xreflabel="Format der Upgradedateien">
5435         <title>Format der Kontrollinformationen</title>
5436
5437         <para>Die Kontrollinformationen sollten sich am Anfang der jeweiligen
5438         Upgradedatei befinden. Jede Zeile, die Kontrollinformationen enthält,
5439         hat dabei das folgende Format:</para>
5440
5441         <para>Für SQL-Upgradedateien:</para>
5442
5443         <programlisting>-- @key: value</programlisting>
5444
5445         <para>Für Perl-Upgradedateien:</para>
5446
5447         <programlisting># @key: value</programlisting>
5448
5449         <para>Leerzeichen vor "<varname>value</varname>" werden
5450         entfernt.</para>
5451
5452         <para>Die folgenden Schlüsselworte werden verarbeitet:</para>
5453
5454         <variablelist>
5455           <varlistentry>
5456             <term><varname>tag</varname></term>
5457
5458             <listitem>
5459               <para>Wird zwingend benötigt. Dies ist der "Name" des Upgrades.
5460               Dieser "tag" kann von anderen Kontrolldateien in ihren
5461               Abhängigkeiten verwendet werden (Schlüsselwort
5462               "<varname>depends</varname>"). Der "tag" ist auch der Name, der
5463               in der Datenbank eingetragen wird.</para>
5464
5465               <para>Normalerweise sollte die Kontrolldatei genau so heißen wie
5466               der "tag", nur mit der Endung ".sql" bzw. "pl".</para>
5467
5468               <para>Ein Tag darf nur aus alphanumerischen Zeichen sowie den
5469               Zeichen _ - ( ) bestehen. Insbesondere sind Leerzeichen nicht
5470               erlaubt und sollten stattdessen mit Unterstrichen ersetzt
5471               werden.</para>
5472             </listitem>
5473           </varlistentry>
5474
5475           <varlistentry>
5476             <term><varname>charset</varname></term>
5477
5478             <listitem>
5479               <para>Empfohlen. Gibt den Zeichensatz an, in dem das Script
5480               geschrieben wurde, z.B. "<literal>UTF-8</literal>". Aus
5481               Kompatibilitätsgründen mit alten Upgrade-Scripten wird bei
5482               Abwesenheit des Tags der Zeichensatz
5483               "<literal>ISO-8859-15</literal>" angenommen.</para>
5484             </listitem>
5485           </varlistentry>
5486
5487           <varlistentry>
5488             <term><varname>description</varname></term>
5489
5490             <listitem>
5491               <para>Benötigt. Eine Beschreibung, was in diesem Update
5492               passiert. Diese wird dem Benutzer beim eigentlichen
5493               Datenbankupdate angezeigt. Während der Tag in englisch gehalten
5494               sein sollte, sollte die Beschreibung auf Deutsch
5495               erfolgen.</para>
5496             </listitem>
5497           </varlistentry>
5498
5499           <varlistentry>
5500             <term><varname>depends</varname></term>
5501
5502             <listitem>
5503               <para>Optional. Eine mit Leerzeichen getrennte Liste von "tags",
5504               von denen dieses Upgradescript abhängt. kivitendo stellt sicher,
5505               dass die in dieser Liste aufgeführten Scripte bereits
5506               durchgeführt wurden, bevor dieses Script ausgeführt wird.</para>
5507
5508               <para>Abhängigkeiten werden rekursiv betrachtet. Wenn also ein
5509               Script "b" existiert, das von Änderungen in "a" abhängt, und
5510               eine neue Kontrolldatei für "c" erstellt wird, die von
5511               Änderungen in "a" und "b" abhängt, so genügt es, in "c" nur den
5512               Tag "b" als Abhängigkeit zu definieren.</para>
5513
5514               <para>Es ist nicht erlaubt, sich selbst referenzierende
5515               Abhängigkeiten zu definieren (z.B. "a" -&gt; "b", "b" -&gt; "c"
5516               und "c" -&gt; "a").</para>
5517             </listitem>
5518           </varlistentry>
5519
5520           <varlistentry>
5521             <term><varname>priority</varname></term>
5522
5523             <listitem>
5524               <para>Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in
5525               der Scripte ausgeführt werden, die die gleichen
5526               Abhängigkeitstiefen besitzen. Fehlt dieser Parameter, so wird
5527               der Wert 1000 benutzt.</para>
5528
5529               <para>Dies ist reine Kosmetik. Für echte Reihenfolgen muss
5530               "depends" benutzt werden. kivitendo sortiert die auszuführenden
5531               Scripte zuerst nach der Abhängigkeitstiefe (wenn "z" von "y"
5532               abhängt und "y" von "x", so hat "z" eine Abhängigkeitstiefe von
5533               2, "y" von 1 und "x" von 0. "x" würde hier zuerst ausgeführt,
5534               dann "y", dann "z"), dann nach der Priorität und bei gleicher
5535               Priorität alphabetisch nach dem "tag".</para>
5536             </listitem>
5537           </varlistentry>
5538
5539           <varlistentry>
5540             <term><varname>ignore</varname></term>
5541
5542             <listitem>
5543               <para>Optional. Falls der Wert auf 1 (true) steht, wird das
5544               Skript bei der Anmeldung ignoriert und entsprechend nicht
5545               ausgeführt.</para>
5546             </listitem>
5547           </varlistentry>
5548         </variablelist>
5549       </sect2>
5550
5551       <sect2 id="db-upgrade-files.dbupgrade-tool"
5552              xreflabel="Hilfsscript dbupgrade2_tool.pl">
5553         <title>Hilfsscript dbupgrade2_tool.pl</title>
5554
5555         <para>Um die Arbeit mit den Abhängigkeiten etwas zu erleichtern,
5556         existiert ein Hilfsscript namens
5557         "<filename>scripts/dbupgrade2_tool.pl</filename>". Es muss aus dem
5558         kivitendo-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool
5559         liest alle Datenbankupgradescripte aus dem Verzeichnis
5560         <filename>sql/Pg-upgrade2</filename> aus. Es benutzt dafür die
5561         gleichen Methoden wie kivitendo selber, sodass alle Fehlersituationen
5562         von der Kommandozeile überprüft werden können.</para>
5563
5564         <para>Wird dem Script kein weiterer Parameter übergeben, so wird nur
5565         eine Überprüfung der Felder und Abhängigkeiten vorgenommen. Man kann
5566         sich aber auch Informationen auf verschiedene Art ausgeben
5567         lassen:</para>
5568
5569         <itemizedlist>
5570           <listitem>
5571             <para>Listenform: "<command>./scripts/dbupgrade2_tool.pl
5572             --list</command>"</para>
5573
5574             <para>Gibt eine Liste aller Scripte aus. Die Liste ist in der
5575             Reihenfolge sortiert, in der kivitendo die Scripte ausführen
5576             würde. Es werden neben der Listenposition der Tag, die
5577             Abhängigkeitstiefe und die Priorität ausgegeben.</para>
5578           </listitem>
5579
5580           <listitem>
5581             <para>Baumform: "<command>./scripts/dbupgrade2_tool.pl
5582             --tree</command>"</para>
5583
5584             <para>Listet alle Tags in Baumform basierend auf den
5585             Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte, von
5586             denen keine anderen abhängen. Die Unterknoten sind Scripte, die
5587             beim übergeordneten Script als Abhängigkeit eingetragen
5588             sind.</para>
5589           </listitem>
5590
5591           <listitem id="db-upgrade-files.dbupgrade-tool.reverse-tree">
5592             <para>Umgekehrte Baumform: "<command>./scripts/dbupgrade2_tool.pl
5593             --rtree</command>"</para>
5594
5595             <para>Listet alle Tags in Baumform basierend auf den
5596             Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte mit
5597             der geringsten Abhängigkeitstiefe. Die Unterknoten sind Scripte,
5598             die das übergeordnete Script als Abhängigkeit eingetragen
5599             haben.</para>
5600           </listitem>
5601
5602           <listitem>
5603             <para>Baumform mit Postscriptausgabe:
5604             "<command>./scripts/dbupgrade2_tool.pl
5605             --graphviz</command>"</para>
5606
5607             <para>Benötigt das Tool "<command>graphviz</command>", um mit
5608             seiner Hilfe die <link
5609             linkend="db-upgrade-files.dbupgrade-tool.reverse-tree">umgekehrte
5610             Baumform</link> in eine Postscriptdatei namens
5611             "<filename>db_dependencies.ps</filename>" auszugeben. Dies ist
5612             vermutlich die übersichtlichste Form, weil hierbei jeder Knoten
5613             nur einmal ausgegeben wird. Bei den Textmodusbaumformen hingegen
5614             können Knoten und all ihre Abhängigkeiten mehrfach ausgegeben
5615             werden.</para>
5616           </listitem>
5617
5618           <listitem>
5619             <para>Scripte, von denen kein anderes Script abhängt:
5620             "<command>./scripts/dbupgrade2_tool.pl --nodeps</command>"</para>
5621
5622             <para>Listet die Tags aller Scripte auf, von denen keine anderen
5623             Scripte abhängen.</para>
5624           </listitem>
5625         </itemizedlist>
5626       </sect2>
5627     </sect1>
5628
5629     <sect1 id="translations-languages" xreflabel="Translations and languages">
5630       <title>Translations and languages</title>
5631
5632       <sect2 id="translations-languages.introduction"
5633              xreflabel="Introduction to translations and languages">
5634         <title>Introduction</title>
5635
5636         <note>
5637           <para>Dieser Abschnitt ist in Englisch geschrieben, um
5638           internationalen Übersetzern die Arbeit zu erleichtern.</para>
5639         </note>
5640
5641         <para>This section describes how localization packages in kivitendo
5642         are built. Currently the only language fully supported is German, and
5643         since most of the internal messages are held in English the English
5644         version is usable too.</para>
5645
5646         <para>A stub version of French is included but not functunal at this
5647         point.</para>
5648       </sect2>
5649
5650       <sect2 id="translations-languages.file-structure"
5651              xreflabel="File structure">
5652         <title>File structure</title>
5653
5654         <para>The structure of locales in kivitendo is:</para>
5655
5656         <programlisting>kivitendo/locale/&lt;langcode&gt;/</programlisting>
5657
5658         <para>where &lt;langcode&gt; stands for an abbreviation of the
5659         language package. The builtin packages use two letter <ulink
5660         url="http://en.wikipedia.org/wiki/ISO_639-1">ISO 639-1</ulink> codes,
5661         but the actual name is not relevant for the program and can easily be
5662         extended to <ulink
5663         url="http://en.wikipedia.org/wiki/IETF_language_tag">IETF language
5664         tags</ulink> (i.e. "en_GB"). In fact the original language packages
5665         from SQL Ledger are named in this way.</para>
5666
5667         <para>In such a language directory the following files are
5668         recognized:</para>
5669
5670         <variablelist>
5671           <varlistentry>
5672             <term>LANGUAGE</term>
5673
5674             <listitem>
5675               <para>This file is mandatory.</para>
5676
5677               <para>The <filename>LANGUAGE</filename> file contains the self
5678               descripted name of the language. It should contain a native
5679               representation first, and in parenthesis an english translation
5680               after that. Example:</para>
5681
5682               <programlisting>Deutsch (German)</programlisting>
5683             </listitem>
5684           </varlistentry>
5685
5686           <varlistentry>
5687             <term>charset</term>
5688
5689             <listitem>
5690               <para>This file should be present.</para>
5691
5692               <para>The <filename>charset</filename> file describes which
5693               charset a language package is written in and applies to all
5694               other language files in the package. It is possible to write
5695               some language packages without an explicit charset, but it is
5696               still strongly recommended. You'll never know in what
5697               environment your language package will be used, and neither
5698               UTF-8 nor Latin1 are guaranteed.</para>
5699
5700               <para>The whole content of this file is a string that can be
5701               recognized as a valid charset encoding. Example:</para>
5702
5703               <programlisting>UTF-8</programlisting>
5704             </listitem>
5705           </varlistentry>
5706
5707           <varlistentry>
5708             <term>all</term>
5709
5710             <listitem>
5711               <para>This file is mandatory.</para>
5712
5713               <para>The central translation file. It is essentially an inline
5714               Perl script autogenerated by <command>locales.pl</command>. To
5715               generate it, generate the directory and the two files mentioned
5716               above, and execute the following command:</para>
5717
5718               <programlisting>scripts/locales.pl &lt;langcode&gt;</programlisting>
5719
5720               <para>Otherwise you can simply copy one of the other languages.
5721               You will be told how many are missing like this:</para>
5722
5723               <programlisting>$ scripts/locales.pl en
5724 English - 0.6% - 2015/2028 missing</programlisting>
5725
5726               <para>A file named "<filename>missing</filename>" will be
5727               generated and can be edited. You can also edit the
5728               "<filename>all</filename>" file directly. Edit everything you
5729               like to fit the target language and execute
5730               <command>locales.pl</command> again. See how the missing words
5731               get fewer.</para>
5732             </listitem>
5733           </varlistentry>
5734
5735           <varlistentry>
5736             <term>Num2text</term>
5737
5738             <listitem>
5739               <para>Legacy code from SQL Ledger. It provides a means for
5740               numbers to be converted into natural language, like
5741               <literal>1523 =&gt; one thousand five hundred twenty
5742               three</literal>. If you want to provide it, it must be inlinable
5743               Perl code which provides a <function>num2text</function> sub. If
5744               an <function>init</function> sub exists it will be executed
5745               first.</para>
5746
5747               <para>Only used in the check and receipt printing module.</para>
5748             </listitem>
5749           </varlistentry>
5750
5751           <varlistentry>
5752             <term>special_chars</term>
5753
5754             <listitem>
5755               <para>kivitendo comes with a lot of interfaces to different
5756               formats, some of which are rather picky with their accepted
5757               charset. The <filename>special_chars</filename> file contains a
5758               listing of chars not suited for different file format and
5759               provides substitutions. It is written in "Simple Ini" style,
5760               containing a block for every file format.</para>
5761
5762               <para>First entry should be the order of substitution for
5763               entries as a whitespace separated list. All entries are
5764               interpolated, so <literal>\n</literal>, <literal>\x20</literal>
5765               and <literal>\\</literal> all work.</para>
5766
5767               <para>After that every entry is a special char that should be
5768               translated when writing text into such a file.</para>
5769
5770               <para>Example:</para>
5771
5772               <programlisting>[Template/XML]
5773 order=&amp; &lt; &gt; \n
5774 &amp;=&amp;amp;
5775 &lt;=&amp;lt;
5776 &gt;=&amp;gt;
5777 \n=&lt;br&gt;</programlisting>
5778
5779               <para>Note the importance of the order in this example.
5780               Substituting &lt; and &gt; befor &amp; would lead to $gt; become
5781               &amp;amp;gt;</para>
5782
5783               <para>For a list of valid formats, see the German
5784               <filename>special_chars</filename> entry. As of this writing the
5785               following are recognized:</para>
5786
5787               <programlisting>HTML
5788 URL@HTML
5789 Template/HTML
5790 Template/XML
5791 Template/LaTeX
5792 Template/OpenDocument
5793 filenames</programlisting>
5794
5795               <para>The last of which is very machine dependant. Remember that
5796               a lot of characters are forbidden by some filesystems, for
5797               exmaple MS Windows doesn't like ':' in its files where Linux
5798               doesn't mind that. If you want the files created with your
5799               language pack to be portable, find all chars that could cause
5800               trouble.</para>
5801             </listitem>
5802           </varlistentry>
5803
5804           <varlistentry>
5805             <term>missing</term>
5806
5807             <listitem>
5808               <para>This file is not a part of the language package
5809               itself.</para>
5810
5811               <para>This is a file generated by
5812               <command>scripts/locales.pl</command> while processing your
5813               locales. It's only to have the missing entries singled out and
5814               does not belong to a language package.</para>
5815             </listitem>
5816           </varlistentry>
5817
5818           <varlistentry>
5819             <term>lost</term>
5820
5821             <listitem>
5822               <para>This file is not a part of the language package
5823               itself.</para>
5824
5825               <para>Another file generated by
5826               <command>scripts/locales.pl</command>. If for any reason a
5827               translation does not appear anymore and can be deleted, it gets
5828               moved here. The last 50 or so entries deleted are saved here in
5829               case you made a typo, so that you don't have to translate
5830               everything again. If a tranlsation is missing, the lost file is
5831               checked first. If you maintain a language package, you might
5832               want to keep this safe somewhere.</para>
5833             </listitem>
5834           </varlistentry>
5835         </variablelist>
5836       </sect2>
5837     </sect1>
5838
5839     <sect1 id="devel.testsuite">
5840       <title>Die kivitendo-Test-Suite</title>
5841
5842       <sect2 id="devel.testsuite.intro">
5843         <title>Einführung</title>
5844
5845         <para>kivitendo enthält eine Suite für automatisierte Tests. Sie basiert auf dem Standard-Perl-Modul <literal>Test::More</literal>.</para>
5846
5847         <para>Die grundlegenden Fakten sind:</para>
5848
5849         <itemizedlist>
5850           <listitem><para>Alle Tests liegen im Unterverzeichnis <filename>t/</filename>.</para></listitem>
5851
5852           <listitem><para>Ein Script (bzw. ein Test) in <filename>f/</filename> enthält einen oder mehrere Testfälle.</para></listitem>
5853
5854           <listitem><para>Alle Dateinamen von Tests enden auf <literal>.t</literal>. Es sind selbstständig ausführbare Perl-Scripte.</para></listitem>
5855
5856           <listitem><para>Die Test-Suite besteht aus der Gesamtheit aller Tests, sprich aller Scripte in <filename>f/</filename>, deren
5857           Dateiname auf <literal>.t</literal> endet.</para></listitem>
5858         </itemizedlist>
5859       </sect2>
5860
5861       <sect2 id="devel.testsuite.prerequisites">
5862         <title>Voraussetzungen</title>
5863
5864         <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>
5865
5866         <itemizedlist>
5867           <listitem><para><literal>Test::Deep</literal> (Debian-Paketname: <literal>libtest-deep-perl</literal>; Fedora Core:
5868           <literal>perl-Test-Deep</literal>; openSUSE: <literal>perl-Test-Deep</literal>)</para></listitem>
5869           <listitem><para><literal>Test::Harness</literal> 3.0.0 oder höher. Dieses Modul ist ab Perl 5.10.1 Bestandteil der
5870           Perl-Distribution und kann für frühere Versionen aus dem <ulink url="http://www.cpan.org">CPAN</ulink> bezogen
5871           werden.</para></listitem>
5872         </itemizedlist>
5873       </sect2>
5874
5875       <sect2 id="devel.testsuite.execution">
5876         <title>
5877           Existierende Tests ausführen
5878         </title>
5879
5880         <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
5881         gezielt einzelne Scripte aus. Für beide Fälle gibt es das Helferscript <filename>t/test.sh</filename>.</para>
5882
5883         <para>Will man die komplette Test-Suite ausführen, so muss man einfach nur <filename>t/test.sh</filename> ohne weitere Parameter aus
5884         dem kivitendo-Basisverzeichnis heraus ausführen.</para>
5885
5886         <para>Um einzelne Test-Scripte auszuführen, übergibt man deren Namen an <filename>t/test.sh</filename>. Beispielsweise:</para>
5887
5888         <programlisting>t/test.sh t/form/format_amount.t t/background_job/known_jobs.t</programlisting>
5889       </sect2>
5890
5891
5892       <sect2 id="devel.testsuite.meaning_of_scripts">
5893         <title>
5894           Bedeutung der verschiedenen Test-Scripte
5895         </title>
5896
5897         <para>Die Test-Suite umfasst Tests sowohl für Funktionen als auch für Programmierstil. Einige besonders zu erwähnende, weil auch
5898         während der Entwicklung nützliche Tests sind:</para>
5899
5900         <itemizedlist>
5901           <listitem><para><filename>t/001compile.t</filename> -- compiliert alle Quelldateien und bricht bei Fehlern sofort ab</para></listitem>
5902           <listitem><para><filename>t/002goodperl.t</filename> -- überprüft alle Perl-Dateien auf Anwesenheit von '<literal>use strict</literal>'-Anweisungen</para></listitem>
5903           <listitem><para><filename>t/003safesys.t</filename> -- überprüft Aufrufe von <function>system()</function> und <function>exec()</function> auf Gültigkeit</para></listitem>
5904           <listitem><para><filename>t/005no_tabs.t</filename> -- überprüft, ob Dateien Tab-Zeichen enthalten</para></listitem>
5905           <listitem><para><filename>t/006spelling.t</filename> -- sucht nach häufigen Rechtschreibfehlern</para></listitem>
5906           <listitem><para><filename>t/011pod.t</filename> -- überprüft die Syntax von Dokumentation im POD-Format auf Gültigkeit</para></listitem>
5907         </itemizedlist>
5908
5909         <para>Weitere Test-Scripte überprüfen primär die Funktionsweise einzelner Funktionen und Module.</para>
5910       </sect2>
5911
5912       <sect2 id="devel.testsuite.create_new">
5913         <title>
5914           Neue Test-Scripte erstellen
5915         </title>
5916
5917         <para>Es wird sehr gern gesehen, wenn neue Funktionalität auch gleich mit einem Test-Script abgesichert wird. Auch bestehende
5918         Funktion darf und soll ausdrücklich nachträglich mit Test-Scripten abgesichert werden.</para>
5919
5920         <sect3 id="devel.testsuite.ideas_for_non_function_tests">
5921           <title>
5922             Ideen für neue Test-Scripte, die keine konkreten Funktionen testen
5923           </title>
5924
5925           <para> Ideen, die abgesehen von Funktions noch nicht umgesetzt wurden:</para>
5926
5927           <itemizedlist>
5928             <listitem><para>Überprüfung auf fehlende symbolische Links</para></listitem>
5929             <listitem><para>Suche nach Nicht-ASCII-Zeichen in Perl-Code-Dateien (mit gewissen Einschränkungen wie das Erlauben von deutschen Umlauten)</para></listitem>
5930             <listitem><para>Test auf DOS-Zeilenenden (\r\n anstelle von nur \n)</para></listitem>
5931             <listitem><para>Überprüfung auf Leerzeichen am Ende von Zeilen</para></listitem>
5932             <listitem><para>Test, ob alle zu übersetzenden Strings in <filename>locale/de/all</filename> vorhanden sind</para></listitem>
5933             <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>
5934           </itemizedlist>
5935         </sect3>
5936
5937         <sect3 id="devel.testsuite.directory_and_test_names">
5938           <title>
5939             Konvention für Verzeichnis- und Dateinamen
5940           </title>
5941
5942           <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>
5943
5944           <itemizedlist>
5945             <listitem><para>Die Dateiendung muss <filename>.t</filename> lauten.</para></listitem>
5946
5947             <listitem><para>Namen sind englisch, komplett klein geschrieben und einzelne Wörter mit Unterstrichten getrennt (beispielsweise
5948             <filename>bad_function_params.t</filename>).</para></listitem>
5949
5950             <listitem><para>Unterverzeichnisse sollten grob nach dem Themenbereich benannt sind, mit dem sich die Scripte darin befassen
5951             (beispielsweise <filename>background_jobs</filename> für Tests rund um Hintergrund-Jobs).</para></listitem>
5952
5953             <listitem><para>Test-Scripte sollten einen überschaubaren Bereich von Funktionalität testen, der logisch zusammenhängend ist
5954             (z.B. nur Tests für eine einzelne Funktion in einem Modul). Lieber mehrere Test-Scripte schreiben.</para></listitem>
5955           </itemizedlist>
5956         </sect3>
5957
5958         <sect3 id="devel.testsuite.minimal_example">
5959           <title>
5960             Minimales Skelett für eigene Scripte
5961           </title>
5962
5963           <para>Der folgenden Programmcode enthält das kleinstmögliche Testscript und kann als Ausgangspunkt für eigene Tests verwendet werden:</para>
5964
5965           <programlisting>use Test::More tests =&gt; 0;
5966
5967 use lib 't';
5968
5969 use Support::TestSetup;
5970
5971 Support::TestSetup::login();</programlisting>
5972
5973           <para>Wird eine vollständig initialisierte kivitendo-Umgebung benötigt (Stichwort: alle globalen Variablen wie
5974           <varname>$::auth</varname>, <varname>$::form</varname> oder <varname>$::lxdebug</varname>), so muss in der Konfigurationsdatei
5975           <filename>config/kivitendo.conf</filename> im Abschnitt <literal>testing.login</literal> ein gültiger Login-Name eingetragen
5976           sein. Dieser wird für die Datenbankverbindung benötigt.</para>
5977
5978           <para>Wir keine vollständig initialisierte Umgebung benötigt, so kann die letzte Zeile <code>Support::TestSetup::login();</code>
5979           weggelassen werden, was die Ausführungszeit des Scripts leicht verringert.</para>
5980         </sect3>
5981       </sect2>
5982     </sect1>
5983
5984     <sect1 id="devel.style-guide">
5985       <title>Stil-Richtlinien</title>
5986
5987       <para>Die folgenden Regeln haben das Ziel, den Code möglichst gut les-
5988       und wartbar zu machen. Dazu gehört zum Einen, dass der Code einheitlich
5989       eingerückt ist, aber auch, dass Mehrdeutigkeit so weit es geht vermieden
5990       wird (Stichworte "Klammern" oder "Hash-Keys").</para>
5991
5992       <para>Diese Regeln sind keine Schikane sondern erleichtern allen das
5993       Leben!</para>
5994
5995       <para>Jeder, der einen Patch schickt, sollte seinen Code vorher
5996       überprüfen. Einige der Regeln lassen sich automatisch überprüfen, andere
5997       nicht.</para>
5998
5999       <orderedlist>
6000         <listitem>
6001           <para>Es werden keine echten Tabs sondern Leerzeichen
6002           verwendet.</para>
6003         </listitem>
6004
6005         <listitem>
6006           <para>Die Einrückung beträgt zwei Leerzeichen. Beispiel:</para>
6007
6008           <programlisting>foreach my $row (@data) {
6009   if ($flag) {
6010     # do something with $row
6011   }
6012
6013   if ($use_modules) {
6014     $row-&gt;{modules} = MODULE-&gt;retrieve(
6015       id   =&gt; $row-&gt;{id},
6016       date =&gt; $use_now ? localtime() : $row-&gt;{time},
6017     );
6018   }
6019
6020   $report-&gt;add($row);
6021 }</programlisting>
6022         </listitem>
6023
6024         <listitem>
6025           <para>Öffnende geschweifte Klammern befinden sich auf der gleichen
6026           Zeile wie der letzte Befehl. Beispiele:</para>
6027
6028           <programlisting>sub debug {
6029   ...
6030 }</programlisting>
6031
6032           <para>oder</para>
6033
6034           <programlisting>if ($form-&gt;{item_rows} &gt; 0) {
6035   ...
6036 }</programlisting>
6037         </listitem>
6038
6039         <listitem>
6040           <para>Schließende geschweifte Klammern sind so weit eingerückt wie
6041           der Befehl / die öffnende schließende Klammer, die den Block
6042           gestartet hat, und nicht auf der Ebene des Inhalts. Die gleichen
6043           Beispiele wie bei 3. gelten.</para>
6044         </listitem>
6045
6046         <listitem>
6047           <para>Die Wörter "<function>else</function>",
6048           "<function>elsif</function>", "<function>while</function>" befinden
6049           sich auf der gleichen Zeile wie schließende geschweifte Klammern.
6050           Beispiele:</para>
6051
6052           <programlisting>if ($form-&gt;{sum} &gt; 1000) {
6053   ...
6054 } elsif ($form-&gt;{sum} &gt; 0) {
6055   ...
6056 } else {
6057   ...
6058 }
6059
6060 do {
6061   ...
6062 } until ($a &gt; 0);</programlisting>
6063         </listitem>
6064
6065         <listitem>
6066           <para>Parameter von Funktionsaufrufen müssen mit runden Klammern
6067           versehen werden. Davon nicht betroffen sind interne Perl-Funktionen,
6068           und grep-ähnliche Operatoren. Beispiel:</para>
6069
6070           <programlisting>$main::lxdebug-&gt;message("Could not find file.");
6071 %options = map { $_ =&gt; 1 } grep { !/^#/ } @config_file;</programlisting>
6072         </listitem>
6073
6074         <listitem>
6075           <para>Verschiedene Klammern, Ihre Ausdrücke und Leerzeichen:</para>
6076
6077           <para>Generell gilt: Hashkeys und Arrayindices sollten nicht durch
6078           Leerzeichen abgesetzt werden. Logische Klammerungen ebensowenig,
6079           Blöcke schon. Beispiel:</para>
6080
6081           <programlisting>if (($form-&gt;{debug} == 1) &amp;&amp; ($form-&gt;{sum} - 100 &lt; 0)) {
6082   ...
6083 }
6084
6085 $array[$i + 1]             = 4;
6086 $form-&gt;{sum}              += $form-&gt;{"row_$i"};
6087 $form-&gt;{ $form-&gt;{index} } += 1;
6088
6089 map { $form-&gt;{sum} += $form-&gt;{"row_$_"} } 1..$rowcount;</programlisting>
6090         </listitem>
6091
6092         <listitem>
6093           <para>Mehrzeilige Befehle</para>
6094
6095           <orderedlist>
6096             <listitem>
6097               <para>Werden die Parameter eines Funktionsaufrufes auf mehrere
6098               Zeilen aufgeteilt, so sollten diese bis zu der Spalte eingerückt
6099               werden, in der die ersten Funktionsparameter in der ersten Zeile
6100               stehen. Beispiel:</para>
6101
6102               <programlisting>$sth = $dbh-&gt;prepare("SELECT * FROM some_table WHERE col = ?",
6103                     $form-&gt;{some_col_value});</programlisting>
6104             </listitem>
6105
6106             <listitem>
6107               <para>Ein Spezialfall ist der ternäre Oprator "?:", der am
6108               besten in einer übersichtlichen Tabellenstruktur organisiert
6109               wird. Beispiel:</para>
6110
6111               <programlisting>my $rowcount = $form-&gt;{"row_$i"} ? $i
6112              : $form-&gt;{oldcount} ? $form-&gt;{oldcount} + 1
6113              :                     $form-&gt;{rowcount} - $form-&gt;{rowbase};</programlisting>
6114             </listitem>
6115           </orderedlist>
6116         </listitem>
6117
6118         <listitem>
6119           <para>Kommentare</para>
6120
6121           <orderedlist>
6122             <listitem>
6123               <para>Kommentare, die alleine in einer Zeile stehen, sollten
6124               soweit wie der Code eingerückt sein.</para>
6125             </listitem>
6126
6127             <listitem>
6128               <para>Seitliche hängende Kommentare sollten einheitlich
6129               formatiert werden.</para>
6130             </listitem>
6131
6132             <listitem>
6133               <para>Sämtliche Kommentare und Sonstiges im Quellcode ist bitte
6134               auf Englisch zu verfassen. So wie ich keine Lust habe,
6135               französischen Quelltext zu lesen, sollte auch der kivitendo
6136               Quelltext für nicht-Deutschsprachige lesbar sein.
6137               Beispiel:</para>
6138
6139               <programlisting>my $found = 0;
6140 while (1) {
6141   last if $found;
6142
6143   # complicated check
6144   $found = 1 if //
6145 }
6146
6147 $i  = 0        # initialize $i
6148 $n  = $i;      # save $i
6149 $i *= $const;  # do something crazy
6150 $i  = $n;      # recover $i</programlisting>
6151             </listitem>
6152           </orderedlist>
6153         </listitem>
6154
6155         <listitem>
6156           <para>Hashkeys sollten nur in Anführungszeichen stehen, wenn die
6157           Interpolation gewünscht ist. Beispiel:</para>
6158
6159           <programlisting>$form-&gt;{sum}      = 0;
6160 $form-&gt;{"row_$i"} = $form-&gt;{"row_$i"} - 5;
6161 $some_hash{42}    = 54;</programlisting>
6162         </listitem>
6163
6164         <listitem>
6165           <para>Die maximale Zeilenlänge ist nicht beschränkt. Zeilenlängen
6166           unterhalb von 79 Zeichen helfen unter bestimmten Bedingungen, aber
6167           wenn die Lesbarkeit unter kurzen Zeilen leidet (wie zum Biespiel in
6168           grossen Tabellen), dann ist Lesbarkeit vorzuziehen.</para>
6169
6170           <para>Als Beispiel sei die Funktion
6171           <function>print_options</function> aus
6172           <filename>bin/mozilla/io.pl</filename> angeführt.</para>
6173         </listitem>
6174
6175         <listitem>
6176           <para>Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind
6177           unerwünscht. Sie führen zu unnötigen Whitespaceänderungen, die diffs
6178           verfälschen.</para>
6179
6180           <para>Emacs und vim haben beide recht einfache Methoden zur
6181           Entfernung von trailing whitespace. Emacs kennt das Kommande
6182           <command>nuke-trailing-whitespace</command>, vim macht das gleiche
6183           manuell über <literal>:%s/\s\+$//e</literal> Mit <literal>:au
6184           BufWritePre * :%s/\s\+$//e</literal> wird das an Speichern
6185           gebunden.</para>
6186         </listitem>
6187
6188         <listitem>
6189           <para>Es wird kein <command>perltidy</command> verwendet.</para>
6190
6191           <para>In der Vergangenheit wurde versucht,
6192           <command>perltidy</command> zu verwenden, um einen einheitlichen
6193           Stil zu erlangen. Es hat sich aber gezeigt, dass
6194           <command>perltidy</command>s sehr eigenwilliges Verhalten, was
6195           Zeilenumbrüche angeht, oftmals gut formatierten Code zerstört. Für
6196           den Interessierten sind hier die
6197           <command>perltidy</command>-Optionen, die grob den beschriebenen
6198           Richtlinien entsprechen:</para>
6199
6200           <programlisting>-syn -i=2 -nt -pt=2 -sbt=2 -ci=2 -ibc -hsc -noll -nsts -nsfs -asc -dsm
6201 -aws -bbc -bbs -bbb -mbl=1 -nsob -ce -nbl -nsbl -cti=0 -bbt=0 -bar -l=79
6202 -lp -vt=1 -vtc=1</programlisting>
6203         </listitem>
6204
6205         <listitem>
6206           <para><varname>STDERR</varname> ist tabu. Unkonditionale
6207           Debugmeldungen auch.</para>
6208
6209           <para>kivitendo bietet mit dem Modul <classname>LXDebug</classname>
6210           einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen
6211           Grund, nach <varname>STDERR</varname> zu schreiben.</para>
6212
6213           <para>Die <classname>LXDebug</classname>-Methode
6214           "<function>message</function>" nimmt als ersten Paramter außerdem
6215           eine Flagmaske, für die die Meldung angezeigt wird, wobei "0" immer
6216           angezeigt wird. Solche Meldungen sollten nicht eingecheckt werden
6217           und werden in den meisten Fällen auch vom Repository
6218           zurückgewiesen.</para>
6219         </listitem>
6220
6221         <listitem>
6222           <para>Alle neuen Module müssen use strict verwenden.</para>
6223
6224           <para><varname>$form</varname>, <varname>$auth</varname>,
6225           <varname>$locale</varname>, <varname>$lxdebug</varname> und
6226           <varname>%myconfig</varname> werden derzeit aus dem main package
6227           importiert (siehe <xref linkend="devel.globals" />. Alle anderen
6228           Konstrukte sollten lexikalisch lokal gehalten werden.</para>
6229         </listitem>
6230       </orderedlist>
6231     </sect1>
6232
6233     <sect1 id="devel.build-doc" xreflabel="Dokumentation erstellen">
6234       <title>Dokumentation erstellen</title>
6235
6236       <sect2 id="devel.build-doc.introduction">
6237         <title>Einführung</title>
6238
6239         <para>Diese Dokumentation ist in <productname>DocBook</productname>
6240         XML geschrieben. Zum Bearbeiten reicht grundsätzlich ein Text-Editor.
6241         Mehr Komfort bekommt man, wenn man einen dedizierten XML-fähigen
6242         Editor nutzt, der spezielle Unterstützung für
6243         <productname>DocBook</productname> mitbringt. Wir empfehlen dafür den
6244         <ulink url="http://www.xmlmind.com/xmleditor/">XMLmind XML
6245         Editor</ulink>, der bei nicht kommerzieller Nutzung kostenlos
6246         ist.</para>
6247       </sect2>
6248
6249       <sect2 id="devel.build-doc.required-software">
6250         <title>Benötigte Software</title>
6251
6252         <para>Bei <productname>DocBook</productname> ist Prinzip, dass
6253         ausschließlich die XML-Quelldatei bearbeitet wird. Aus dieser werden
6254         dann mit entsprechenden Stylesheets andere Formate wie PDF oder HTML
6255         erzeugt. Bei kivitendo übernimmt diese Aufgabe das Shell-Script
6256         <command>scripts/build_doc.sh</command>.</para>
6257
6258         <para>Das Script benötigt zur Konvertierung verschiedene
6259         Softwarekomponenten, die im normalen kivitendo-Betrieb nicht benötigt
6260         werden:</para>
6261
6262         <itemizedlist>
6263           <listitem>
6264             <para><ulink
6265             url="http://www.oracle.com/technetwork/java/index.html">Java</ulink>
6266             in einer halbwegs aktuellen Version</para>
6267           </listitem>
6268
6269           <listitem>
6270             <para>Das Java-Build-System <ulink
6271             url="http://ant.apache.org/">Apache Ant</ulink></para>
6272           </listitem>
6273
6274           <listitem>
6275             <para>Das Dokumentations-System Dobudish für
6276             <productname>DocBook</productname> 4.5, eine Zusammenstellung
6277             diverser Stylesheets und Grafiken zur Konvertierung von
6278             <productname>DocBook</productname> XML in andere Formate. Das
6279             Paket, das benötigt wird, ist zum Zeitpunkt der
6280             Dokumentationserstellung
6281             <filename>dobudish-nojre-1.1.4.zip</filename>, aus auf <ulink
6282             url="http://code.google.com/p/dobudish/downloads/list">code.google.com</ulink>
6283             bereitsteht.</para>
6284           </listitem>
6285         </itemizedlist>
6286
6287         <para>Apache Ant sowie ein dazu passendes Java Runtime Environment
6288         sind auf allen gängigen Plattformen verfügbar. Beispiel für
6289         Debian/Ubuntu:</para>
6290
6291         <programlisting>apt-get install ant openjdk-7-jre</programlisting>
6292
6293         <para>Nach dem Download von Dobudish muss Dobudish im Unterverzeichnis
6294         <filename>doc/build</filename> entpackt werden. Beispiel unter der
6295         Annahme, das <productname>Dobudish</productname> in
6296         <filename>$HOME/Downloads</filename> heruntergeladen wurde:</para>
6297
6298         <programlisting>cd doc/build
6299 unzip $HOME/Downloads/dobudish-nojre-1.1.4.zip</programlisting>
6300       </sect2>
6301
6302       <sect2 id="devel.build-doc.build">
6303         <title>PDFs und HTML-Seiten erstellen</title>
6304
6305         <para>Die eigentliche Konvertierung erfolgt nach Installation der
6306         benötigten Software mit einem einfachen Aufruf direkt aus dem
6307         kivitendo-Installationsverzeichnis heraus:</para>
6308
6309         <programlisting>./scripts/build_doc.sh</programlisting>
6310       </sect2>
6311
6312       <sect2 id="devel.build-doc.repository">
6313         <title>Einchecken in das Git-Repository</title>
6314
6315         <para>Sowohl die XML-Datei als auch die erzeugten PDF- und
6316         HTML-Dateien sind Bestandteil des Git-Repositories. Daraus folgt, dass
6317         nach Änderungen am XML die PDF- und HTML-Dokumente ebenfalls gebaut
6318         und alles zusammen in einem Commit eingecheckt werden sollten.</para>
6319
6320         <para>Die "<filename>dobudish</filename>"-Verzeichnisse bzw.
6321         symbolischen Links gehören hingegen nicht in das Repository.</para>
6322       </sect2>
6323     </sect1>
6324   </chapter>
6325 </book>