X-Git-Url: http://wagnertech.de/git?a=blobdiff_plain;ds=sidebyside;f=doc%2Fhtml%2Fch04s04.html;h=f53c439c78776ae0d4c97cadf43fd381e778d634;hb=c62a6cabffc11bdb2d3fda2025fef2f3d07c5ba9;hp=15aaa08b3d403c4abaf1be25d68edb2af66d89f5;hpb=8041f98c3befcfffba2149954e84695a23d9b4a6;p=kivitendo-erp.git diff --git a/doc/html/ch04s04.html b/doc/html/ch04s04.html index 15aaa08b3..f53c439c7 100644 --- a/doc/html/ch04s04.html +++ b/doc/html/ch04s04.html @@ -1,100 +1,140 @@
-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.
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:
This file is mandatory.
The LANGUAGE
file 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)
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.
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 a num2text
sub. If
- an init
sub exists it will be executed
- first.
Only used in the check and receipt printing module.
kivitendo comes with a lot of interfaces to different
- formats, some of which are rather picky with their accepted
- charset. The special_chars
file 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_chars
entry. 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 dependant. Remember that - a lot of characters are forbidden by some filesystems, for - exmaple 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.
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.
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.
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 +4.4. SQL-Upgradedateien Datenbankupgrades werden über einzelne Upgrade-Scripte + gesteuert, die sich im Verzeichnis +
sql/Pg-upgrade2
befinden. In diesem Verzeichnis + muss pro Datenbankupgrade eine Datei existieren, die neben den + eigentlich auszuführenden SQL- oder Perl-Befehlen einige + Kontrollinformationen enthält.Kontrollinformationen definieren Abhängigkeiten und Prioritäten, + sodass Datenbankscripte zwar in einer sicheren Reihenfolge ausgeführt + werden (z.B. darf ein
ALTER TABLE
erst ausgeführt + werden, wenn die Tabelle mitCREATE TABLE
angelegt + wurde), diese Reihenfolge aber so flexibel ist, dass man keine + Versionsnummern braucht.kivitendo merkt sich dabei, welches der Upgradescripte in +
sql/Pg-upgrade2
bereits durchgeführt wurde und + führt diese nicht erneut aus. Dazu dient die Tabelle + "schema_info
", die bei der Anmeldung automatisch + angelegt wird.Die Kontrollinformationen sollten sich am Anfang der jeweiligen + Upgradedatei befinden. Jede Zeile, die Kontrollinformationen enthält, + hat dabei das folgende Format:
Für SQL-Upgradedateien:
-- @key: valueFür Perl-Upgradedateien:
# @key: valueLeerzeichen vor "
value
" werden + entfernt.Die folgenden Schlüsselworte werden verarbeitet:
- +
tag
+Wird zwingend benötigt. Dies ist der "Name" des Upgrades. + Dieser "tag" kann von anderen Kontrolldateien in ihren + Abhängigkeiten verwendet werden (Schlüsselwort + "
depends
"). Der "tag" ist auch der Name, der + in der Datenbank eingetragen wird.Normalerweise sollte die Kontrolldatei genau so heiÃen wie + der "tag", nur mit der Endung ".sql" bzw. "pl".
Ein Tag darf nur aus alphanumerischen Zeichen sowie den + Zeichen _ - ( ) bestehen. Insbesondere sind Leerzeichen nicht + erlaubt und sollten stattdessen mit Unterstrichen ersetzt + werden.
- +
charset
+Empfohlen. Gibt den Zeichensatz an, in dem das Script + geschrieben wurde, z.B. "
UTF-8
". Aus + Kompatibilitätsgründen mit alten Upgrade-Scripten wird bei + Abwesenheit des Tags für SQL-Upgradedateien der Zeichensatz + "ISO-8859-15
" angenommen. Perl-Upgradescripte + hingegen müssen immer in UTF-8 encodiert sein und sollten + demnach auch ein "use utf8;
" + enthalten.- +
description
+Benötigt. Eine Beschreibung, was in diesem Update + passiert. Diese wird dem Benutzer beim eigentlichen + Datenbankupdate angezeigt. Während der Tag in Englisch gehalten + sein sollte, sollte die Beschreibung auf Deutsch + erfolgen.
- +
depends
+Optional. Eine mit Leerzeichen getrennte Liste von "tags", + von denen dieses Upgradescript abhängt. kivitendo stellt sicher, + dass die in dieser Liste aufgeführten Scripte bereits + durchgeführt wurden, bevor dieses Script ausgeführt wird.
Abhängigkeiten werden rekursiv betrachtet. Wenn also ein + Script "b" existiert, das von Ãnderungen in "a" abhängt, und + eine neue Kontrolldatei für "c" erstellt wird, die von + Ãnderungen in "a" und "b" abhängt, so genügt es, in "c" nur den + Tag "b" als Abhängigkeit zu definieren.
Es ist nicht erlaubt, sich selbst referenzierende + Abhängigkeiten zu definieren (z.B. "a" -> "b", "b" -> "c" + und "c" -> "a").
- +
priority
+Optional. Ein Zahlenwert, der die Reihenfolge bestimmt, in + der Scripte ausgeführt werden, die die gleichen + Abhängigkeitstiefen besitzen. Fehlt dieser Parameter, so wird + der Wert 1000 benutzt.
Dies ist reine Kosmetik. Für echte Reihenfolgen muss + "depends" benutzt werden. kivitendo sortiert die auszuführenden + Scripte zuerst nach der Abhängigkeitstiefe (wenn "z" von "y" + abhängt und "y" von "x", so hat "z" eine Abhängigkeitstiefe von + 2, "y" von 1 und "x" von 0. "x" würde hier zuerst ausgeführt, + dann "y", dann "z"), dann nach der Priorität und bei gleicher + Priorität alphabetisch nach dem "tag".
- +
ignore
+Optional. Falls der Wert auf 1 (true) steht, wird das + Skript bei der Anmeldung ignoriert und entsprechend nicht + ausgeführt.
In Perl geschriebene Datenbankscripte werden nicht einfach so + ausgeführt sondern müssen sich an gewisse Konventionen halten. Dafür + bekommen sie aber auch einige Komfortfunktionen bereitgestellt.
Ein Upgradescript stellt dabei eine vollständige Objektklasse + dar, die vom Elternobjekt "
SL::DBUpgrade2::Base
" + erben und eine Funktion namens "run
" zur Verfügung + stellen muss. Das Script wird ausgeführt, indem eine Instanz dieser + Klasse erzeugt und darauf die erwähnte "run
" + aufgerufen wird.Zu beachten ist, dass sich der Paketname der Datei aus dem Wert + für "
@tag
" ableitet. Dabei werden alle Zeichen, die + in Paketnamen ungültig wären (gerade Bindestriche), durch Unterstriche + ersetzt. Insgesamt sieht der Paketname wie folgt aus: + "SL::DBUpgrade2::tag
".Welche Komfortfunktionen zur Verfügung stehen, erfahren Sie in + der Perl-Dokumentation zum oben genannten Modul; aufzurufen mit + "perldoc SL/DBUpgrade2/Base.pm".
Ein Mindestgerüst eines gültigen Perl-Upgradescriptes sieht wie + folgt aus:
# @tag: beispiel-upgrade-file42 +# @description: Ein schönes Beispielscript +# @depends: release_3_1_0 +package SL::DBUpgrade2::beispiel_upgrade_file42; +use strict; use utf8; -# 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', +use parent qw(SL::DBUpgrade2::Base); -$self->{more_texts} = { +sub run { + my ($self) = @_; - 'Ship via' => 'Terms of delivery', - 'Shipping Point' => 'Delivery time', + # hier Aktionen ausführen + + return 1; } -- -
Um die Arbeit mit den Abhängigkeiten etwas zu erleichtern,
+ existiert ein Hilfsscript namens
+ "scripts/dbupgrade2_tool.pl
". Es muss aus dem
+ kivitendo-ERP-Basisverzeichnis heraus aufgerufen werden. Dieses Tool
+ liest alle Datenbankupgradescripte aus dem Verzeichnis
+ sql/Pg-upgrade2
aus. Es benutzt dafür die
+ gleichen Methoden wie kivitendo selber, sodass alle Fehlersituationen
+ von der Kommandozeile überprüft werden können.
Wird dem Script kein weiterer Parameter übergeben, so wird nur + eine Ãberprüfung der Felder und Abhängigkeiten vorgenommen. Man kann + sich aber auch Informationen auf verschiedene Art ausgeben + lassen:
Listenform: "./scripts/dbupgrade2_tool.pl + --list"
Gibt eine Liste aller Scripte aus. Die Liste ist in der + Reihenfolge sortiert, in der kivitendo die Scripte ausführen + würde. Es werden neben der Listenposition der Tag, die + Abhängigkeitstiefe und die Priorität ausgegeben.
Baumform: "./scripts/dbupgrade2_tool.pl + --tree"
Listet alle Tags in Baumform basierend auf den + Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte, von + denen keine anderen abhängen. Die Unterknoten sind Scripte, die + beim übergeordneten Script als Abhängigkeit eingetragen + sind.
Umgekehrte Baumform: "./scripts/dbupgrade2_tool.pl + --rtree"
Listet alle Tags in Baumform basierend auf den + Abhängigkeiten auf. Die "Wurzelknoten" sind dabei die Scripte mit + der geringsten Abhängigkeitstiefe. Die Unterknoten sind Scripte, + die das übergeordnete Script als Abhängigkeit eingetragen + haben.
Baumform mit Postscriptausgabe: + "./scripts/dbupgrade2_tool.pl + --graphviz"
Benötigt das Tool "graphviz", um mit
+ seiner Hilfe die umgekehrte
+ Baumform in eine Postscriptdatei namens
+ "db_dependencies.ps
" auszugeben. Dies ist
+ vermutlich die übersichtlichste Form, weil hierbei jeder Knoten
+ nur einmal ausgegeben wird. Bei den Textmodusbaumformen hingegen
+ können Knoten und all ihre Abhängigkeiten mehrfach ausgegeben
+ werden.
Scripte, von denen kein anderes Script abhängt: + "./scripts/dbupgrade2_tool.pl --nodeps"
Listet die Tags aller Scripte auf, von denen keine anderen + Scripte abhängen.