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.
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
Die eigentliche Konvertierung erfolgt nach Installation der - benötigten Software mit einem einfachen Aufruf direkt aus dem - kivitendo-Installationsverzeichnis heraus:
./scripts/build_doc.sh
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.
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
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});Ein Spezialfall ist der ternäre Operator "?:", 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
Kommentare, die alleine in einer Zeile stehen, sollten + soweit wie der Code eingerückt sein.
Seitliche hängende Kommentare sollten einheitlich + formatiert werden.
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 $iHashkeys 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.