4.4. Translations and languages

4.4.1. Introduction

Anmerkung

Dieser Abschnitt ist in Englisch geschrieben, um + 4.4. Translations and languages

4.4. Translations and languages
ZurÃ¼ck	Kapitel 4. Entwicklerdokumentation	Weiter

4.4. Translations and languages

4.4.1. Introduction

	Anmerkung
	Dieser Abschnitt ist in Englisch geschrieben, um internationalen Ãbersetzern die Arbeit zu erleichtern.

This section describes how localization packages in kivitendo are built. Currently the only language fully supported is German, and since most of the internal messages are held in English the English @@ -78,4 +78,4 @@ filenames

The last of which is very machine dependant. Remember that case you made a typo, so that you don't have to translate everything again. If a tranlsation is missing, the lost file is checked first. If you maintain a language package, you might - want to keep this safe somewhere.

ZurÃ¼ck	Nach oben	Weiter
4.3. SQL-Upgradedateien	Zum Anfang	4.5. Stil-Richtlinien

\ No newline at end of file + want to keep this safe somewhere.

ZurÃ¼ck	Nach oben	Weiter
4.3. SQL-Upgradedateien	Zum Anfang	4.5. Die kivitendo-Test-Suite

\ No newline at end of file diff --git a/doc/html/ch04s05.html b/doc/html/ch04s05.html index 9d3743f07..87fee7702 100644 --- a/doc/html/ch04s05.html +++ b/doc/html/ch04s05.html @@ -1,120 +1,41 @@ - 4.5. Stil-Richtlinien

4.5. Stil-Richtlinien
ZurÃ¼ck	Kapitel 4. Entwicklerdokumentation	Weiter

4.5. Stil-Richtlinien

Die folgenden Regeln haben das Ziel, den Code mÃ¶glichst gut les- - und wartbar zu machen. Dazu gehÃ¶rt zum Einen, dass der Code einheitlich - eingerÃ¼ckt ist, aber auch, dass Mehrdeutigkeit so weit es geht vermieden - wird (Stichworte "Klammern" oder "Hash-Keys").

Diese Regeln sind keine Schikane sondern erleichtern allen das - Leben!

Jeder, der einen Patch schickt, sollte seinen Code vorher - Ã¼berprÃ¼fen. Einige der Regeln lassen sich automatisch Ã¼berprÃ¼fen, andere - nicht.

Es werden keine echten Tabs sondern Leerzeichen - verwendet.

Die EinrÃ¼ckung betrÃ¤gt zwei Leerzeichen. Beispiel:

foreach my $row (@data) {
- if ($flag) {
- # do something with $row
- }
+ 4.5. Die kivitendo-Test-Suite4.5. Die kivitendo-Test-Suite
ZurÃ¼ck Kapitel 4. Entwicklerdokumentation Weiter
4.5. Die kivitendo-Test-Suite
4.5.1. EinfÃ¼hrung
kivitendo enthÃ¤lt eine Suite fÃ¼r automatisierte Tests. Sie basiert auf dem Standard-Perl-Modul Test::More.
Die grundlegenden Fakten sind:
Alle Tests liegen im Unterverzeichnis t/.
Ein Script (bzw. ein Test) in f/ enthÃ¤lt einen oder mehrere TestfÃ¤lle.
Alle Dateinamen von Tests enden auf .t. Es sind selbststÃ¤ndig ausfÃ¼hrbare Perl-Scripte.
Die Test-Suite besteht aus der Gesamtheit aller Tests, sprich aller Scripte in f/, deren
+ Dateiname auf .t endet.
4.5.2. Voraussetzungen
FÃ¼r die AusfÃ¼hrung werden neben den fÃ¼r kivitendo eh schon benÃ¶tigten Module noch weitere Perl-Module benÃ¶tigt. Diese sind:

+ Test::Deep (Debian-Paketname: libtest-deep-perl; Fedora Core:
+ perl-Test-Deep; openSuSE: perl-Test-Deep)
4.5.3.
+ Existierende Tests ausfÃ¼hren
+
Es gibt mehrere MÃ¶glichkeiten zum AusfÃ¼hren der Tests: entweder, man lÃ¤sst alle Tests auf einmal ausfÃ¼hren, oder man fÃ¼hrt
+ gezielt einzelne Scripte aus. FÃ¼r beide FÃ¤lle gibt es das Helferscript t/test.sh.
Will man die komplette Test-Suite ausfÃ¼hren, so muss man einfach nur t/test.sh ohne weitere Parameter aus
+ dem kivitendo-Basisverzeichnis heraus ausfÃ¼hren.
Um einzelne Test-Scripte auszufÃ¼hren, Ã¼bergibt man deren Namen an t/test.sh. Beispielsweise:
t/test.sh t/form/format_amount.t t/background_job/known_jobs.t
4.5.4.
+ Bedeutung der verschiedenen Test-Scripte
+
Die Test-Suite umfasst Tests sowohl fÃ¼r Funktionen als auch fÃ¼r Programmierstil. Einige besonders zu erwÃ¤hnende, weil auch
+ wÃ¤hrend der Entwicklung nÃ¼tzliche Tests sind:

+ t/001compile.t -- compiliert alle Quelldateien und bricht bei Fehlern sofort ab

+ t/002goodperl.t -- Ã¼berprÃ¼ft alle Perl-Dateien auf Anwesenheit von 'use strict'-Anweisungen

+ t/003safesys.t -- Ã¼berprÃ¼ft Aufrufe von system() und exec() auf GÃ¼ltigkeit

+ t/005no_tabs.t -- Ã¼berprÃ¼ft, ob Dateien Tab-Zeichen enthalten

+ t/006spelling.t -- sucht nach hÃ¤ufigen Rechtschreibfehlern

+ t/011pod.t -- Ã¼berprÃ¼ft die Syntax von Dokumentation im POD-Format auf GÃ¼ltigkeit
Weitere Test-Scripte Ã¼berprÃ¼fen primÃ¤r die Funktionsweise einzelner Funktionen und Module.
4.5.5.
+ Neue Test-Scripte erstellen
+
Es wird sehr gern gesehen, wenn neue FunktionalitÃ¤t auch gleich mit einem Test-Script abgesichert wird. Auch bestehende
+ Funktion darf und soll ausdrÃ¼cklich nachtrÃ¤glich mit Test-Scripten abgesichert werden.
4.5.5.1.
+ Ideen fÃ¼r neue Test-Scripte, die keine konkreten Funktionen testen
+
Ideen, die abgesehen von Funktions noch nicht umgesetzt wurden:
ÃberprÃ¼fung auf fehlende symbolische Links
Suche nach Nicht-ASCII-Zeichen in Perl-Code-Dateien (mit gewissen EinschrÃ¤nkungen wie das Erlauben von deutschen Umlauten)
Test auf DOS-Zeilenenden (\r\n anstelle von nur \n)
ÃberprÃ¼fung auf Leerzeichen am Ende von Zeilen
Test, ob alle zu Ã¼bersetzenden Strings in locale/de/all vorhanden sind
Test, ob alle Webseiten-Templates in templates/webpages mit vom Perl-Modul Template compiliert werden kÃ¶nnen
4.5.5.2.
+ Konvention fÃ¼r Verzeichnis- und Dateinamen
+
Es gibt momentan eine wenige Richtlinien, wie Test-Scripte zu benennen sind. Bitte die folgenden Punkte als Richtlinie betrachten und ihnen soweit es geht folgen:
Die Dateiendung muss .t lauten.
Namen sind englisch, komplett klein geschrieben und einzelne WÃ¶rter mit Unterstrichten getrennt (beispielsweise
+ bad_function_params.t).
Unterverzeichnisse sollten grob nach dem Themenbereich benannt sind, mit dem sich die Scripte darin befassen
+ (beispielsweise background_jobs fÃ¼r Tests rund um Hintergrund-Jobs).
Test-Scripte sollten einen Ã¼berschaubaren Bereich von FunktionalitÃ¤t testen, der logisch zusammenhÃ¤ngend ist
+ (z.B. nur Tests fÃ¼r eine einzelne Funktion in einem Modul). Lieber mehrere Test-Scripte schreiben.
4.5.5.3.
+ Minimales Skelett fÃ¼r eigene Scripte
+
Der folgenden Programmcode enthÃ¤lt das kleinstmÃ¶gliche Testscript und kann als Ausgangspunkt fÃ¼r eigene Tests verwendet werden:
use Test::More tests => 0;

- if ($use_modules) {
- $row->{modules} = MODULE->retrieve(
- id => $row->{id},
- date => $use_now ? localtime() : $row->{time},
- );
- }
+use lib 't';

- $report->add($row);
-}

Ãffnende geschweifte Klammern befinden sich auf der gleichen - Zeile wie der letzte Befehl. Beispiele:
```
sub debug {
-  ...
-}
```
oder
```
if ($form->{item_rows} > 0) {
-  ...
-}
```
SchlieÃende geschweifte Klammern sind so weit eingerÃ¼ckt wie - der Befehl / die Ã¶ffnende schlieÃende Klammer, die den Block - gestartet hat, und nicht auf der Ebene des Inhalts. Die gleichen - Beispiele wie bei 3. gelten.
Die WÃ¶rter "else", - "elsif", "while" befinden - sich auf der gleichen Zeile wie schlieÃende geschweifte Klammern. - Beispiele:
```
if ($form->{sum} > 1000) {
-  ...
-} elsif ($form->{sum} > 0) {
-  ...
-} else {
-  ...
-}
+use Support::TestSetup;
 
-do {
-  ...
-} until ($a > 0);
```
Parameter von Funktionsaufrufen mÃ¼ssen mit runden Klammern - versehen werden. Davon nicht betroffen sind interne Perl-Funktionen, - und grep-Ã¤hnliche Operatoren. Beispiel:
```
$main::lxdebug->message("Could not find file.");
-%options = map { $_ => 1 } grep { !/^#/ } @config_file;
```

Verschiedene Klammern, Ihre AusdrÃ¼cke und Leerzeichen:

Generell gilt: Hashkeys und Arrayindices sollten nicht durch - Leerzeichen abgesetzt werden. Logische Klammerungen ebensowenig, - BlÃ¶cke schon. Beispiel:

if (($form->{debug} == 1) && ($form->{sum} - 100 < 0)) {
-  ...
-}
-
-$array[$i + 1]             = 4;
-$form->{sum}              += $form->{"row_$i"};
-$form->{ $form->{index} } += 1;
-
-map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;

Mehrzeilige Befehle
1. Werden die Parameter eines Funktionsaufrufes auf mehrere - Zeilen aufgeteilt, so sollten diese bis zu der Spalte eingerÃ¼ckt - werden, in der die ersten Funktionsparameter in der ersten Zeile - stehen. Beispiel:
```
$sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?",
-                    $form->{some_col_value});
```
2. Ein Spezialfall ist der ternÃ¤re Oprator "?:", der am - besten in einer Ã¼bersichtlichen Tabellenstruktur organisiert - wird. Beispiel:
```
my $rowcount = $form->{"row_$i"} ? $i
-             : $form->{oldcount} ? $form->{oldcount} + 1
-             :                     $form->{rowcount} - $form->{rowbase};
```
Kommentare
1. Kommentare, die alleine in einer Zeile stehen, sollten - soweit wie der Code eingerÃ¼ckt sein.
2. Seitliche hÃ¤ngende Kommentare sollten einheitlich - formatiert werden.
3. SÃ¤mtliche Kommentare und Sonstiges im Quellcode ist bitte - auf Englisch zu verfassen. So wie ich keine Lust habe, - franzÃ¶sischen Quelltext zu lesen, sollte auch der kivitendo - Quelltext fÃ¼r nicht-Deutschsprachige lesbar sein. - Beispiel:
```
my $found = 0;
-while (1) {
-  last if $found;
-
-  # complicated check
-  $found = 1 if //
-}
-
-$i  = 0        # initialize $i
-$n  = $i;      # save $i
-$i *= $const;  # do something crazy
-$i  = $n;      # recover $i
```
Hashkeys sollten nur in AnfÃ¼hrungszeichen stehen, wenn die - Interpolation gewÃ¼nscht ist. Beispiel:
```
$form->{sum}      = 0;
-$form->{"row_$i"} = $form->{"row_$i"} - 5;
-$some_hash{42}    = 54;
```
Die maximale ZeilenlÃ¤nge ist nicht beschrÃ¤nkt. ZeilenlÃ¤ngen - unterhalb von 79 Zeichen helfen unter bestimmten Bedingungen, aber - wenn die Lesbarkeit unter kurzen Zeilen leidet (wie zum Biespiel in - grossen Tabellen), dann ist Lesbarkeit vorzuziehen.
Als Beispiel sei die Funktion - print_options aus - bin/mozilla/io.pl angefÃ¼hrt.
Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind - unerwÃ¼nscht. Sie fÃ¼hren zu unnÃ¶tigen WhitespaceÃ¤nderungen, die diffs - verfÃ¤lschen.
Emacs und vim haben beide recht einfache Methoden zur - Entfernung von trailing whitespace. Emacs kennt das Kommande - nuke-trailing-whitespace, vim macht das gleiche - manuell Ã¼ber :%s/\s\+$//e Mit :au - BufWritePre * :%s/\s\+$//e wird das an Speichern - gebunden.
Es wird kein perltidy verwendet.
In der Vergangenheit wurde versucht, - perltidy zu verwenden, um einen einheitlichen - Stil zu erlangen. Es hat sich aber gezeigt, dass - perltidys sehr eigenwilliges Verhalten, was - ZeilenumbrÃ¼che angeht, oftmals gut formatierten Code zerstÃ¶rt. FÃ¼r - den Interessierten sind hier die - perltidy-Optionen, die grob den beschriebenen - Richtlinien entsprechen:
```
-syn -i=2 -nt -pt=2 -sbt=2 -ci=2 -ibc -hsc -noll -nsts -nsfs -asc -dsm
--aws -bbc -bbs -bbb -mbl=1 -nsob -ce -nbl -nsbl -cti=0 -bbt=0 -bar -l=79
--lp -vt=1 -vtc=1
```
- STDERR ist tabu. Unkonditionale - Debugmeldungen auch.
kivitendo bietet mit dem Modul LXDebug - einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen - Grund, nach STDERR zu schreiben.
Die LXDebug-Methode - "message" nimmt als ersten Paramter auÃerdem - eine Flagmaske, fÃ¼r die die Meldung angezeigt wird, wobei "0" immer - angezeigt wird. Solche Meldungen sollten nicht eingecheckt werden - und werden in den meisten FÃ¤llen auch vom Repository - zurÃ¼ckgewiesen.
Alle neuen Module mÃ¼ssen use strict verwenden.
- $form, $auth, - $locale, $lxdebug und - %myconfig werden derzeit aus dem main package - importiert (siehe Globale Variablen. Alle anderen - Konstrukte sollten lexikalisch lokal gehalten werden.

ZurÃ¼ck	Nach oben	Weiter
4.4. Translations and languages	Zum Anfang	4.6. Dokumentation erstellen

\ No newline at end of file +Support::TestSetup::login();

Wird eine vollstÃ¤ndig initialisierte kivitendo-Umgebung benÃ¶tigt (Stichwort: alle globalen Variablen wie + $::auth, $::form oder $::lxdebug), so muss in der Konfigurationsdatei + config/kivitendo.conf im Abschnitt testing.login ein gÃ¼ltiger Login-Name eingetragen + sein. Dieser wird fÃ¼r die Datenbankverbindung benÃ¶tigt.

Wir keine vollstÃ¤ndig initialisierte Umgebung benÃ¶tigt, so kann die letzte Zeile Support::TestSetup::login(); + weggelassen werden, was die AusfÃ¼hrungszeit des Scripts leicht verringert.

ZurÃ¼ck	Nach oben	Weiter
4.4. Translations and languages	Zum Anfang	4.6. Stil-Richtlinien

\ No newline at end of file diff --git a/doc/html/ch04s06.html b/doc/html/ch04s06.html index e99f3e0d1..a5580b2ea 100644 --- a/doc/html/ch04s06.html +++ b/doc/html/ch04s06.html @@ -1,38 +1,120 @@ - 4.6. Dokumentation erstellen

4.6. Dokumentation erstellen
ZurÃ¼ck	Kapitel 4. Entwicklerdokumentation

4.6. Dokumentation erstellen

4.6.1. EinfÃ¼hrung

Diese Dokumentation ist in DocBookâ¢ - XML geschrieben. Zum Bearbeiten reicht grundsÃ¤tzlich ein Text-Editor. - Mehr Komfort bekommt man, wenn man einen dedizierten XML-fÃ¤higen - Editor nutzt, der spezielle UnterstÃ¼tzung fÃ¼r - DocBookâ¢ mitbringt. Wir empfehlen dafÃ¼r den - XMLmind XML - Editor, der bei nicht kommerzieller Nutzung kostenlos - ist.

4.6.2. BenÃ¶tigte Software

Bei DocBookâ¢ ist Prinzip, dass - ausschlieÃlich die XML-Quelldatei bearbeitet wird. Aus dieser werden - dann mit entsprechenden Stylesheets andere Formate wie PDF oder HTML - erzeugt. Bei kivitendo Ã¼bernimmt diese Aufgabe das Shell-Script - scripts/build_doc.sh.

Das Script benÃ¶tigt zur Konvertierung verschiedene - Softwarekomponenten, die im normalen kivitendo-Betrieb nicht benÃ¶tigt - werden:

- Java - in einer halbwegs aktuellen Version
Das Java-Build-System Apache Ant -
Das Dokumentations-System Dobudish fÃ¼r - DocBookâ¢ 4.5, eine Zusammenstellung - diverser Stylesheets und Grafiken zur Konvertierung von - DocBookâ¢ XML in andere Formate. Das - Paket, das benÃ¶tigt wird, ist zum Zeitpunkt der - Dokumentationserstellung - dobudish-nojre-1.1.4.zip, aus auf code.google.com - bereitsteht.

Apache Ant sowie ein dazu passendes Java Runtime Environment - sind auf allen gÃ¤ngigen Plattformen verfÃ¼gbar. Beispiel fÃ¼r - Debian/Ubuntu:

apt-get install ant openjdk-7-jre

Nach dem Download von Dobudish muss Dobudish im Unterverzeichnis - doc/build entpackt werden. Beispiel unter der - Annahme, das Dobudishâ¢ in - $HOME/Downloads heruntergeladen wurde:

cd doc/build
-unzip $HOME/Downloads/dobudish-nojre-1.1.4.zip

4.6.3. PDFs und HTML-Seiten erstellen

Die eigentliche Konvertierung erfolgt nach Installation der - benÃ¶tigten Software mit einem einfachen Aufruf direkt aus dem - kivitendo-Installationsverzeichnis heraus:

./scripts/build_doc.sh

4.6.4. Einchecken in das Git-Repository

Sowohl die XML-Datei als auch die erzeugten PDF- und - HTML-Dateien sind Bestandteil des Git-Repositories. Daraus folgt, dass - nach Ãnderungen am XML die PDF- und HTML-Dokumente ebenfalls gebaut - und alles zusammen in einem Commit eingecheckt werden sollten.

Die "dobudish"-Verzeichnisse bzw. - symbolischen Links gehÃ¶ren hingegen nicht in das Repository.

ZurÃ¼ck	Nach oben
4.5. Stil-Richtlinien	Zum Anfang

\ No newline at end of file + 4.6. Stil-Richtlinien

4.6. Stil-Richtlinien
ZurÃ¼ck	Kapitel 4. Entwicklerdokumentation	Weiter

4.6. Stil-Richtlinien

Die folgenden Regeln haben das Ziel, den Code mÃ¶glichst gut les- + und wartbar zu machen. Dazu gehÃ¶rt zum Einen, dass der Code einheitlich + eingerÃ¼ckt ist, aber auch, dass Mehrdeutigkeit so weit es geht vermieden + wird (Stichworte "Klammern" oder "Hash-Keys").

Diese Regeln sind keine Schikane sondern erleichtern allen das + Leben!

Jeder, der einen Patch schickt, sollte seinen Code vorher + Ã¼berprÃ¼fen. Einige der Regeln lassen sich automatisch Ã¼berprÃ¼fen, andere + nicht.

Es werden keine echten Tabs sondern Leerzeichen + verwendet.

Die EinrÃ¼ckung betrÃ¤gt zwei Leerzeichen. Beispiel:

foreach my $row (@data) {
+  if ($flag) {
+    # do something with $row
+  }
+
+  if ($use_modules) {
+    $row->{modules} = MODULE->retrieve(
+      id   => $row->{id},
+      date => $use_now ? localtime() : $row->{time},
+    );
+  }
+
+  $report->add($row);
+}

Ãffnende geschweifte Klammern befinden sich auf der gleichen + Zeile wie der letzte Befehl. Beispiele:
```
sub debug {
+  ...
+}
```
oder
```
if ($form->{item_rows} > 0) {
+  ...
+}
```
SchlieÃende geschweifte Klammern sind so weit eingerÃ¼ckt wie + der Befehl / die Ã¶ffnende schlieÃende Klammer, die den Block + gestartet hat, und nicht auf der Ebene des Inhalts. Die gleichen + Beispiele wie bei 3. gelten.
Die WÃ¶rter "else", + "elsif", "while" befinden + sich auf der gleichen Zeile wie schlieÃende geschweifte Klammern. + Beispiele:
```
if ($form->{sum} > 1000) {
+  ...
+} elsif ($form->{sum} > 0) {
+  ...
+} else {
+  ...
+}
+
+do {
+  ...
+} until ($a > 0);
```
Parameter von Funktionsaufrufen mÃ¼ssen mit runden Klammern + versehen werden. Davon nicht betroffen sind interne Perl-Funktionen, + und grep-Ã¤hnliche Operatoren. Beispiel:
```
$main::lxdebug->message("Could not find file.");
+%options = map { $_ => 1 } grep { !/^#/ } @config_file;
```

Verschiedene Klammern, Ihre AusdrÃ¼cke und Leerzeichen:

Generell gilt: Hashkeys und Arrayindices sollten nicht durch + Leerzeichen abgesetzt werden. Logische Klammerungen ebensowenig, + BlÃ¶cke schon. Beispiel:

if (($form->{debug} == 1) && ($form->{sum} - 100 < 0)) {
+  ...
+}
+
+$array[$i + 1]             = 4;
+$form->{sum}              += $form->{"row_$i"};
+$form->{ $form->{index} } += 1;
+
+map { $form->{sum} += $form->{"row_$_"} } 1..$rowcount;

Mehrzeilige Befehle
1. Werden die Parameter eines Funktionsaufrufes auf mehrere + Zeilen aufgeteilt, so sollten diese bis zu der Spalte eingerÃ¼ckt + werden, in der die ersten Funktionsparameter in der ersten Zeile + stehen. Beispiel:
```
$sth = $dbh->prepare("SELECT * FROM some_table WHERE col = ?",
+                    $form->{some_col_value});
```
2. Ein Spezialfall ist der ternÃ¤re Oprator "?:", der am + besten in einer Ã¼bersichtlichen Tabellenstruktur organisiert + wird. Beispiel:
```
my $rowcount = $form->{"row_$i"} ? $i
+             : $form->{oldcount} ? $form->{oldcount} + 1
+             :                     $form->{rowcount} - $form->{rowbase};
```
Kommentare
1. Kommentare, die alleine in einer Zeile stehen, sollten + soweit wie der Code eingerÃ¼ckt sein.
2. Seitliche hÃ¤ngende Kommentare sollten einheitlich + formatiert werden.
3. SÃ¤mtliche Kommentare und Sonstiges im Quellcode ist bitte + auf Englisch zu verfassen. So wie ich keine Lust habe, + franzÃ¶sischen Quelltext zu lesen, sollte auch der kivitendo + Quelltext fÃ¼r nicht-Deutschsprachige lesbar sein. + Beispiel:
```
my $found = 0;
+while (1) {
+  last if $found;
+
+  # complicated check
+  $found = 1 if //
+}
+
+$i  = 0        # initialize $i
+$n  = $i;      # save $i
+$i *= $const;  # do something crazy
+$i  = $n;      # recover $i
```
Hashkeys sollten nur in AnfÃ¼hrungszeichen stehen, wenn die + Interpolation gewÃ¼nscht ist. Beispiel:
```
$form->{sum}      = 0;
+$form->{"row_$i"} = $form->{"row_$i"} - 5;
+$some_hash{42}    = 54;
```
Die maximale ZeilenlÃ¤nge ist nicht beschrÃ¤nkt. ZeilenlÃ¤ngen + unterhalb von 79 Zeichen helfen unter bestimmten Bedingungen, aber + wenn die Lesbarkeit unter kurzen Zeilen leidet (wie zum Biespiel in + grossen Tabellen), dann ist Lesbarkeit vorzuziehen.
Als Beispiel sei die Funktion + print_options aus + bin/mozilla/io.pl angefÃ¼hrt.
Trailing Whitespace, d.h. Leerzeichen am Ende von Zeilen sind + unerwÃ¼nscht. Sie fÃ¼hren zu unnÃ¶tigen WhitespaceÃ¤nderungen, die diffs + verfÃ¤lschen.
Emacs und vim haben beide recht einfache Methoden zur + Entfernung von trailing whitespace. Emacs kennt das Kommande + nuke-trailing-whitespace, vim macht das gleiche + manuell Ã¼ber :%s/\s\+$//e Mit :au + BufWritePre * :%s/\s\+$//e wird das an Speichern + gebunden.
Es wird kein perltidy verwendet.
In der Vergangenheit wurde versucht, + perltidy zu verwenden, um einen einheitlichen + Stil zu erlangen. Es hat sich aber gezeigt, dass + perltidys sehr eigenwilliges Verhalten, was + ZeilenumbrÃ¼che angeht, oftmals gut formatierten Code zerstÃ¶rt. FÃ¼r + den Interessierten sind hier die + perltidy-Optionen, die grob den beschriebenen + Richtlinien entsprechen:
```
-syn -i=2 -nt -pt=2 -sbt=2 -ci=2 -ibc -hsc -noll -nsts -nsfs -asc -dsm
+-aws -bbc -bbs -bbb -mbl=1 -nsob -ce -nbl -nsbl -cti=0 -bbt=0 -bar -l=79
+-lp -vt=1 -vtc=1
```
+ STDERR ist tabu. Unkonditionale + Debugmeldungen auch.
kivitendo bietet mit dem Modul LXDebug + einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen + Grund, nach STDERR zu schreiben.
Die LXDebug-Methode + "message" nimmt als ersten Paramter auÃerdem + eine Flagmaske, fÃ¼r die die Meldung angezeigt wird, wobei "0" immer + angezeigt wird. Solche Meldungen sollten nicht eingecheckt werden + und werden in den meisten FÃ¤llen auch vom Repository + zurÃ¼ckgewiesen.
Alle neuen Module mÃ¼ssen use strict verwenden.
+ $form, $auth, + $locale, $lxdebug und + %myconfig werden derzeit aus dem main package + importiert (siehe Globale Variablen. Alle anderen + Konstrukte sollten lexikalisch lokal gehalten werden.

ZurÃ¼ck	Nach oben	Weiter
4.5. Die kivitendo-Test-Suite	Zum Anfang	4.7. Dokumentation erstellen

\ No newline at end of file diff --git a/doc/html/ch04s07.html b/doc/html/ch04s07.html new file mode 100644 index 000000000..0727e304c --- /dev/null +++ b/doc/html/ch04s07.html @@ -0,0 +1,38 @@ + + + 4.7. Dokumentation erstellen

4.7. Dokumentation erstellen
ZurÃ¼ck	Kapitel 4. Entwicklerdokumentation

4.7. Dokumentation erstellen

4.7.1. EinfÃ¼hrung

Diese Dokumentation ist in DocBookâ¢ + XML geschrieben. Zum Bearbeiten reicht grundsÃ¤tzlich ein Text-Editor. + Mehr Komfort bekommt man, wenn man einen dedizierten XML-fÃ¤higen + Editor nutzt, der spezielle UnterstÃ¼tzung fÃ¼r + DocBookâ¢ mitbringt. Wir empfehlen dafÃ¼r den + XMLmind XML + Editor, der bei nicht kommerzieller Nutzung kostenlos + ist.

4.7.2. BenÃ¶tigte Software

Bei DocBookâ¢ ist Prinzip, dass + ausschlieÃlich die XML-Quelldatei bearbeitet wird. Aus dieser werden + dann mit entsprechenden Stylesheets andere Formate wie PDF oder HTML + erzeugt. Bei kivitendo Ã¼bernimmt diese Aufgabe das Shell-Script + scripts/build_doc.sh.

Das Script benÃ¶tigt zur Konvertierung verschiedene + Softwarekomponenten, die im normalen kivitendo-Betrieb nicht benÃ¶tigt + werden:

+ Java + in einer halbwegs aktuellen Version
Das Java-Build-System Apache Ant +
Das Dokumentations-System Dobudish fÃ¼r + DocBookâ¢ 4.5, eine Zusammenstellung + diverser Stylesheets und Grafiken zur Konvertierung von + DocBookâ¢ XML in andere Formate. Das + Paket, das benÃ¶tigt wird, ist zum Zeitpunkt der + Dokumentationserstellung + dobudish-nojre-1.1.4.zip, aus auf code.google.com + bereitsteht.

Apache Ant sowie ein dazu passendes Java Runtime Environment + sind auf allen gÃ¤ngigen Plattformen verfÃ¼gbar. Beispiel fÃ¼r + Debian/Ubuntu:

apt-get install ant openjdk-7-jre

Nach dem Download von Dobudish muss Dobudish im Unterverzeichnis + doc/build entpackt werden. Beispiel unter der + Annahme, das Dobudishâ¢ in + $HOME/Downloads heruntergeladen wurde:

cd doc/build
+unzip $HOME/Downloads/dobudish-nojre-1.1.4.zip

4.7.3. PDFs und HTML-Seiten erstellen

Die eigentliche Konvertierung erfolgt nach Installation der + benÃ¶tigten Software mit einem einfachen Aufruf direkt aus dem + kivitendo-Installationsverzeichnis heraus:

./scripts/build_doc.sh

4.7.4. Einchecken in das Git-Repository

Sowohl die XML-Datei als auch die erzeugten PDF- und + HTML-Dateien sind Bestandteil des Git-Repositories. Daraus folgt, dass + nach Ãnderungen am XML die PDF- und HTML-Dokumente ebenfalls gebaut + und alles zusammen in einem Commit eingecheckt werden sollten.

Die "dobudish"-Verzeichnisse bzw. + symbolischen Links gehÃ¶ren hingegen nicht in das Repository.

ZurÃ¼ck	Nach oben
4.6. Stil-Richtlinien	Zum Anfang

\ No newline at end of file diff --git a/doc/html/index.html b/doc/html/index.html index 83d2b300c..b30a65dfd 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -3,4 +3,10 @@ kivitendo: Installation, Konfiguration, Entwicklung

kivitendo: Installation, Konfiguration, Entwicklung
		Weiter

kivitendo: Installation, Konfiguration, Entwicklung

Inhaltsverzeichnis

1. Aktuelle Hinweise

2. Installation und Grundkonfiguration

2.1. BenÃ¶tigte Software und Pakete

2.1.1. Betriebssystem
2.1.2. Pakete

2.2. Manuelle Installation des Programmpaketes

2.3. kivitendo-Konfigurationsdatei

2.3.1. EinfÃ¼hrung
2.3.2. Abschnitte und Parameter
2.3.3. Versionen vor 2.6.3

2.4. Anpassung der PostgreSQL-Konfiguration

2.4.1. ZeichensÃ¤tze/die Verwendung von UTF-8
2.4.2. Ãnderungen an Konfigurationsdateien
2.4.3. Erweiterung fÃ¼r servergespeicherte Prozeduren
2.4.4. Datenbankbenutzer anlegen

2.5. Webserver-Konfiguration

2.5.1. Grundkonfiguration mittels CGI
2.5.2. Konfiguration fÃ¼r FastCGI/FCGI

2.6. Der Task-Server

2.6.1. VerfÃ¼gbare und notwendige Konfigurationsoptionen
2.6.2. Automatisches Starten des Task-Servers beim Booten
2.6.3. Wie der Task-Server gestartet und beendet wird
2.6.4. Task-Server mit mehreren Mandanten

2.7. Benutzerauthentifizierung und Administratorpasswort

2.7.1. Grundlagen zur Benutzerauthentifizierung
2.7.2. Administratorpasswort
2.7.3. Authentifizierungsdatenbank
2.7.4. PasswortÃ¼berprÃ¼fung
2.7.5. Name des Session-Cookies
2.7.6. Anlegen der Authentifizierungsdatenbank

2.8. Benutzer- und Gruppenverwaltung

2.8.1. ZusammenhÃ¤nge
2.8.2. Datenbanken anlegen
2.8.3. Gruppen anlegen
2.8.4. Benutzer anlegen
2.8.5. Gruppenmitgliedschaften verwalten
2.8.6. Migration alter Installationen

2.9. Drucken mit kivitendo

2.10. OpenDocument-Vorlagen

2.11. Konfiguration zur EinnahmenÃ¼berschussrechnung/Bilanzierung: EUR

2.11.1. EinfÃ¼hrung
2.11.2. Konfigurationsparameter
2.11.3. Festlegen der Parameter
2.11.4. Bemerkungen zu Bestandsmethode
2.11.5. Bekannte Probleme

2.12. SKR04 19% Umstellung fÃ¼r innergemeinschaftlichen Erwerb

2.12.1. EinfÃ¼hrung
2.12.2. Konto 3804 manuell anlegen

2.13. kivitendo ERP verwenden

3. Features und Funktionen

3.1. Wiederkehrende Rechnungen

3.1.1. EinfÃ¼hrung
3.1.2. Konfiguration
3.1.3. Auflisten
3.1.4. Erzeugung der eigentlichen Rechnungen
3.1.5. Erste Rechnung fÃ¼r aktuellen Monat erstellen

3.2. Dokumentenvorlagen und verfÃ¼gbare Variablen

3.2.1. EinfÃ¼hrung
3.2.2. Variablen ausgeben
3.2.3. Verwendung in Druckbefehlen
3.2.4. Anfang und Ende der Tags verÃ¤ndern
3.2.5. Zuordnung von den Dateinamen zu den Funktionen
3.2.6. Sprache, Drucker und E-Mail
3.2.7. Allgemeine Variablen, die in allen Vorlagen vorhanden sind
3.2.8. Variablen in Rechnungen
3.2.9. Variablen in Mahnungen und Rechnungen Ã¼ber MahngebÃ¼hren
3.2.10. Variablen in anderen Vorlagen
3.2.11. BlÃ¶cke, bedingte Anweisungen und Schleifen
3.2.12. Markup-Code zur Textformatierung innerhalb von - Formularen

3.3. Excel-Vorlagen

3.3.1. Zusammenfassung
3.3.2. Bedienung
3.3.3. Variablensyntax
3.3.4. EinschrÃ¤nkungen

4. Entwicklerdokumentation

4.1. Globale Variablen

4.1.1. Wie sehen globale Variablen in Perl aus?
4.1.2. Warum sind globale Variablen ein Problem?
4.1.3. Kanonische globale Variablen
4.1.4. Ehemalige globale Variablen

4.2. Entwicklung unter FastCGI

4.2.1. Allgemeines
4.2.2. Programmende und Ausnahmen
4.2.3. Globale Variablen
4.2.4. Performance und Statistiken
4.2.5. Bekannte Probleme

4.3. SQL-Upgradedateien

4.3.1. EinfÃ¼hrung
4.3.2. Format der Kontrollinformationen
4.3.3. Hilfsscript dbupgrade2_tool.pl

4.4. Translations and languages

4.4.1. Introduction
4.4.2. File structure

4.5. Stil-Richtlinien

4.6. Dokumentation erstellen

4.6.1. EinfÃ¼hrung
4.6.2. BenÃ¶tigte Software
4.6.3. PDFs und HTML-Seiten erstellen
4.6.4. Einchecken in das Git-Repository

		Weiter
		Kapitel 1. Aktuelle Hinweise

\ No newline at end of file + Formularen

3.3. Excel-Vorlagen

3.3.1. Zusammenfassung
3.3.2. Bedienung
3.3.3. Variablensyntax
3.3.4. EinschrÃ¤nkungen

4. Entwicklerdokumentation

4.1. Globale Variablen

4.1.1. Wie sehen globale Variablen in Perl aus?
4.1.2. Warum sind globale Variablen ein Problem?
4.1.3. Kanonische globale Variablen
4.1.4. Ehemalige globale Variablen

4.2. Entwicklung unter FastCGI

4.2.1. Allgemeines
4.2.2. Programmende und Ausnahmen
4.2.3. Globale Variablen
4.2.4. Performance und Statistiken
4.2.5. Bekannte Probleme

4.3. SQL-Upgradedateien

4.3.1. EinfÃ¼hrung
4.3.2. Format der Kontrollinformationen
4.3.3. Hilfsscript dbupgrade2_tool.pl

4.4. Translations and languages

4.4.1. Introduction
4.4.2. File structure

4.5. Die kivitendo-Test-Suite

4.5.1. EinfÃ¼hrung
4.5.2. Voraussetzungen
4.5.3. + Existierende Tests ausfÃ¼hren +
4.5.4. + Bedeutung der verschiedenen Test-Scripte +
4.5.5. + Neue Test-Scripte erstellen +

4.6. Stil-Richtlinien

4.7. Dokumentation erstellen

4.7.1. EinfÃ¼hrung
4.7.2. BenÃ¶tigte Software
4.7.3. PDFs und HTML-Seiten erstellen
4.7.4. Einchecken in das Git-Repository

		Weiter
		Kapitel 1. Aktuelle Hinweise

\ No newline at end of file diff --git a/doc/kivitendo-Dokumentation.pdf b/doc/kivitendo-Dokumentation.pdf index 9840d8358..881218ef3 100644 Binary files a/doc/kivitendo-Dokumentation.pdf and b/doc/kivitendo-Dokumentation.pdf differ diff --git a/t/README b/t/README deleted file mode 100644 index 07276f3f5..000000000 --- a/t/README +++ /dev/null @@ -1,41 +0,0 @@ -Testsuite for Lx-Office. - -These tests are a means to ensure basic sanity among the lx-office source -files. The test framework was originally written by the guys of Bugzilla, and -has been modified to cope with the Lx-Office structure. - -To run a full test use the shell script t/test.sh. -You can also run every test with the perl interpreter like this: - -$ perl t/001compile.t - -A makefile for an automated make test would be highly appreciated. - - - -The Tests: - -001compile.t: Tries to compile every source file. Bails out if any errors occur. -002goodperl.t: Checks every perl source file for taint, warnings and strict. - While taint is not seen mandatory, warnings and strict are. -003safesys: Checks is system() and exec() calls are fully qualified. -004template.t defunct! -005no_tabs.t checks every file for the \t Tab char. don't use tabs please. -006spelling.t checks for common spelling errors. -011pod.t checks if POD syntax is correct. - - -Wanted Tests: - -- module check -- check if symlinks are missing. -- check for anything outside lower ascii in pl/pm files (only place for complex - coding is locale) -- check for msdos line endings -- check for trailing whitespace -- Devise a test to check if there are modifications to locales without a - locales.pl run. -- Test if parse_template can compile all html templates. - -and later: -- spec tests for pure backend modules like Form.pm and Common.pm

4.4. Translations and languages

4.4.1. Introduction

4.4. Translations and languages

4.4.1. Introduction

4.5. Stil-Richtlinien

4.5. Die kivitendo-Test-Suite

4.5.1. EinfÃ¼hrung

4.5.2. Voraussetzungen

4.5.3. + Existierende Tests ausfÃ¼hren +

4.5.4. + Bedeutung der verschiedenen Test-Scripte +

4.5.5. + Neue Test-Scripte erstellen +

4.5.5.1. + Ideen fÃ¼r neue Test-Scripte, die keine konkreten Funktionen testen +

4.5.5.2. + Konvention fÃ¼r Verzeichnis- und Dateinamen +

4.5.5.3. + Minimales Skelett fÃ¼r eigene Scripte +

4.6. Dokumentation erstellen

4.6.1. EinfÃ¼hrung

4.6.2. BenÃ¶tigte Software

4.6.3. PDFs und HTML-Seiten erstellen

4.6.4. Einchecken in das Git-Repository

4.6. Stil-Richtlinien

4.7. Dokumentation erstellen

4.7.1. EinfÃ¼hrung

4.7.2. BenÃ¶tigte Software

4.7.3. PDFs und HTML-Seiten erstellen

4.7.4. Einchecken in das Git-Repository

kivitendo: Installation, Konfiguration, Entwicklung