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