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. Translations and languages ![[Anmerkung]](system/docbook-xsl/images/note.png)
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 + version is usable too.
\ No newline at end of file +The structure of locales in kivitendo is:
kivitendo/locale/<langcode>/
where <langcode> stands for an abbreviation of the + language package. The builtin packages use two letter ISO 639-1 codes, + but the actual name is not relevant for the program and can easily be + extended to IETF language + tags (i.e. "en_GB"). In fact the original language packages + from SQL Ledger are named in this way.
In such a language directory the following files are + recognized:
- LANGUAGE
This file is mandatory.
The
LANGUAGEfile contains the self + descripted name of the language. It should contain a native + representation first, and in parenthesis an english translation + after that. Example:Deutsch (German)
- all
This file is mandatory.
The central translation file. It is essentially an inline + Perl script autogenerated by locales.pl. To + generate it, generate the directory and the two files mentioned + above, and execute the following command:
scripts/locales.pl <langcode>
Otherwise you can simply copy one of the other languages. + You will be told how many are missing like this:
$ scripts/locales.pl en +English - 0.6% - 2015/2028 missing
A file named "
missing" will be + generated and can be edited. You can also edit the + "all" file directly. Edit everything you + like to fit the target language and execute + locales.pl again. See how the missing words + get fewer.- Num2text
Legacy code from SQL Ledger. It provides a means for + numbers to be converted into natural language, like +
1523 => one thousand five hundred twenty + three. If you want to provide it, it must be inlinable + Perl code which provides anum2textsub. If + aninitsub exists it will be executed + first.Only used in the check and receipt printing module.
- special_chars
kivitendo comes with a lot of interfaces to different + formats, some of which are rather picky with their accepted + charset. The
special_charsfile contains a + listing of chars not suited for different file format and + provides substitutions. It is written in "Simple Ini" style, + containing a block for every file format.First entry should be the order of substitution for + entries as a whitespace separated list. All entries are + interpolated, so
\n,\x20+ and\\all work.After that every entry is a special char that should be + translated when writing text into such a file.
Example:
[Template/XML] +order=& < > \n +&=& +<=< +>=> +\n=<br>
Note the importance of the order in this example. + Substituting < and > befor & would lead to $gt; become + &gt;
For a list of valid formats, see the German +
special_charsentry. As of this writing the + following are recognized:HTML +URL@HTML +Template/HTML +Template/XML +Template/LaTeX +Template/OpenDocument +filenames
The last of which is very machine dependent. Remember that + a lot of characters are forbidden by some filesystems, for + example MS Windows doesn't like ':' in its files where Linux + doesn't mind that. If you want the files created with your + language pack to be portable, find all chars that could cause + trouble.
- missing
This file is not a part of the language package + itself.
This is a file generated by + scripts/locales.pl while processing your + locales. It's only to have the missing entries singled out and + does not belong to a language package.
- lost
This file is not a part of the language package + itself.
Another file generated by + scripts/locales.pl. If for any reason a + translation does not appear anymore and can be deleted, it gets + moved here. The last 50 or so entries deleted are saved here in + 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.
- more/all
This subdir and file is not a part of the language package + itself.
If the directory more exists and contains a file called + all it will be parsed in addition to the mandatory all (see + above). The file is useful if you want to change some + translations for the current installation without conflicting + further upgrades. The file is not autogenerated and has the same + format as the all, but needs another key (more_texts). See the + german translation for an example or copy the following code: +
+#!/usr/bin/perl +# -*- coding: utf-8; -*- +# vim: fenc=utf-8 - if ($use_modules) { - $row->{modules} = MODULE->retrieve( - id => $row->{id}, - date => $use_now ? localtime() : $row->{time}, - ); - } +use utf8; - $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)) { - ... -} +# These are additional texts for custom translations. +# The format is the same as for the normal file all, only +# with another key (more_texts instead of texts). +# The file has the form of 'english text' => 'foreign text', -$array[$i + 1] = 4; -$form->{sum} += $form->{"row_$i"}; -$form->{ $form->{index} } += 1; +$self->{more_texts} = { -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 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
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 // + 'Ship via' => 'Terms of delivery', + 'Shipping Point' => 'Delivery time', } - -$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_optionsaus -bin/mozilla/io.plangefü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\+$//eMit:au - BufWritePre * :%s/\s\+$//ewird 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
-
STDERRist tabu. Unkonditionale - Debugmeldungen auch.kivitendo bietet mit dem Modul
LXDebug- einen brauchbaren Trace-/Debug-Mechanismus. Es gibt also keinen - Grund, nachSTDERRzu 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,$lxdebugund -%myconfigwerden derzeit aus dem main package - importiert (siehe Globale Variablen. Alle anderen - Konstrukte sollten lexikalisch lokal gehalten werden.
+