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