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