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