KDE TechBase - User contributions [en]

Development/Tutorials/API Documentation (de)

2008-12-28T20:09:16Z

DrSlowDecay: /* Beliebte Fehler */ partly translated

{{Template:I18n/Language Navigation Bar|Development/Tutorials/API Documentation}}
__TOC__
{{Box|Definition|
'''API (''Application Programming Interface'') Dokumentation''' ist die Dokumentation eines ''Programmes'' und seiner Schnittstellen. Durch Dokumentation wird einem Entwickler, der mit oder an dem Programm arbeitet, erklärt, wie Dinge funktionieren und wie und welche Methoden aufzurufen sind.

API Dokumentation wird machmal auch API Referenz Handbuch (API reference manual) genannt. Es muß nicht ''nur'' ein Referenz Handbuch sein, obwohl es umfangreiches zusätzliches Material, wie Anleitungen, Zeitleisten, etc., enthalten kann. Auf dieser Seite wird alles Material welches die API eines Codes dokumentiert und erklärt "apidox" genannt.

Gute apidox benötigt etwas Mühe zum schreiben -- doch sicherlich weniger Mühe als gute ''Benutzer'' Dokumentation, da du als Entwickler für andere Entwickler schreibst und eklärst wie Code funktioniert und was er tun soll. So dein Publikum ist bereit damit zu arbeiten. Der Vorteil von apidox zeigt sich, wenn jemand anderes (oder sogar du selbst einige Monate später) den Code (wieder)verwenden oder erweitern möchte. Gute apidox bedeutet, dass jemand neues kommen kann, den Code schnell versteht und nützliche Patches erstellen kann. Gerade für Bibliotheken kann apidox es ermöglichen, diese wie eine Black Box zu benutzen (und so sollte es auch sein), da die benötigte Dokumentation vorliegt und die Dokumentation sich nicht in den tiefen des (vielleicht gar nicht vorliegenden) C codes befindet.|100%}}

== Vorwort ==

Mit APIDOX wird es anderen Entwicklern ermöglicht, auf ein Programm zuzugreifen. Sie sind nicht unbedingt notwenig doch sie helfen neuen Leuten, die an dem Programm arebeiten möchten oder den Code ohne große Änderungen wiederverwenden möchten, sicherlich eine Menge.

Ein Blick auf [http://doc.trolltech.com/latest/ die Qt Dokumentation (englisch)] ermöglicht es, einen Eindruck von guter apidox Dokumentation zu bekommen. Dort sieht man eine Stilkonsistenz, die sich durch die gesamte Dokumentation zieht. Dadurch kann man eine Menge über Qt lernen, nur indem man die Dokumentation liest. Es ist nicht notwendig, die Anleitungsprogramme auszuführen oder den Quellcode zu lesen um herauszufinden, was ein Parameter in einer bestimmten Methode einer Bibliothek macht. Es wird alles bereits erläutert.

Apidox zu schreiben besteht aus zwei Teilen. Der erste Teil ist technischer Natur: Man muß den Code verstehen, der dokumentiert werden soll, oder zumindest wissen, was er tun soll und wie er benutzt werden muss. Der andere Teil ist reine Disziplin: apidox ist am nützlichsten, wenn es sorgfältig und ausführlich benutzt wird.

Dieses Dokument versucht den apidox Prozess nicht zu ausführlich werden zu lassen, indem es einige dirkekte Tips gibt, wie man apidox schreibt. Es gibt dann doch die [[Policies/Library Documentation Policy|library apidox policies (englisch)]], die sehr viel strenger sind. Es schadet nicht, auch dort mal einen Blick reinzuwerfen.

{{note (de)|Die eigentliche Beispieldokumentation auf dieser Seite wird nicht übersetzt, da API Dokumentation in der Regel auf englisch verfasst werden, um eine internationale Mitarbeit zu ermöglichen}}

== APIDOX Basics ==

APIDOX werden durch das [http://www.doxygen.org Doxygen] Dokumentationswerkzeug verarbeitet. Dieses Werkzeug liest den Quellcode der Applikation (oder Bibliothek) und erzeugt schön formatierte Dokumentation daraus. Es gibt ein gutes [http://www.stack.nl/~dimitri/doxygen/manual.html Referenz Handbuch (auf englisch)] -- doch für die Grundlagen muß dieses nicht vollständig gelesen werden.

{{Tip|Doxygen muß für die Arbeit an apidox der Applikation nicht installiert sein. Alle paar Stunden erzeugt das [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] apidox für alle bekannten KDE Module. Logfiles und die eigentlichen Apidox werden ebenfalls bereitgestellt, um Fehlermeldungen zu entdecken und diese zu beheben. Das ist zwar nicht die schellste Methode apidox zu schreiben und zu korrigieren, doch es erledigt diese Aufgabe. Ein paar Stunden Arbeit am Tag, um an der apidox zu arbeiten, reichen aus.}}

{{Tip|Hast du Doxygen installiert und möchtest die apidox erzeugen, benutze das kdedoxygen.sh Skript wie es in [[Development/Tools/apidox|apidox (englisch)]] beschrieben ist.}}

Die Grundlagen von apidox sind einfach und machen Spaß: Man schreibt einfach Kommentare in den Code, die erklären wofür dieser ist. Diese Kommetare sind fast das gleiche wie das, was man sowieso in die header des Codes schreiben muß, so ist das ganze also nicht so schwer.

APIDOX werden in speziellen Kommentaren geschrieben. Diese Kommentare starten mit /** (Schrägstrich, Stern, Stern) -- und das ist es, was sie besonders macht. Der Rest des Kommentars ist einfacher Text, der den Teil des Programms beschreibt. Dieser Text wird vom Doxygen Prozessor interpretiert, damit dadurch passende Beschreibungen der Parameter und Rückgabewerte erfolgen kann. Doch die Dokumentation ist recht unkompliziert: Man schreibt einfach, was eine Methode tut innerhalb von /** und */, so wie folgendes Beispiel:

<code cppqt>
/** This method increases the sexyness of Kontact and should as
* such be called whenever possible (i.e. instead of having idle
* time, you might think of calling this method and helping
* Kontact gain even more popularity). You might even insert it
* into your own event loop to ensure it is called as often as
* possible. If these calls decrease the number of new features,
* it's still no problem to call it.
*/
void incSexyness(KInstance *instance);
</code>

Für eine vernünftige apidox muß jedes "Ding" des Programms dokumentiert werden. "Dinge" sind hierbei Verzeichnisse, Dateien, Namensräume, Klassen, Methoden, Aufzählungen und Variablen. Man kann eventuell Dateien und Verzeichnisse auslassen und sich nur auf die letzteren Punkte konzentrieren. Komplette apidox sehen ungefähr so aus:

<code cppqt>
/** Namespace for KDE network-related classes */
namespace KDENetwork {
/** Wrapper for a TCP/IP socket */
class Socket {
public:
/** Constructor. Calls listen() on some random high port. */
Socket();
private:
int fd;
};
}
</code>

Wie man sieht, ist jede Schachtelungsebene der eben erwähnten "Dinge" mit einem Kommentar versehen -- Der Namensraum, die Klasse und die Methode. Private "Dinge" benötigen keine apidox, protected "Dinge" jedoch schon.

Es ist wichtig, jede einzelne Schachtelungsebene zu dokumentieren, denn läßt man einen Ebene aus, ignoriert Doxygen die inneren ebenso und man findet diese nicht mehr wieder. Angenommen man würde im obigen Beispiel die Klassendokumentation weglassen, dann würde die Dokumentation für die Methode Socket() ebenfalls verschwinden. Das ist eine der typischen Fallen beim Schreiben von apidox.

Und wenn man nur eine Erklärung für jeden Teil seines Programmes schreibt, hat man schon einen großen Teil des Weges zu einer kompletten apidox hinter sich gelassen. Diese Erklärungen zu schreiben macht das Programm einfacher für andere Entwickler zu verstehen und zeigt einem oft schon sub-optimale Designs oder Namenswahlen. Auf diese Art gewinnen beide Seiten.

Man findet in der Liste von unterstützen Tags auch Beispiele für ausgefallenere apidox -- Erklärung von Parametern oder wie man die apidox mit Beispielen und Personendaten versieht. Es lohnt sich auch nachzusehen, wie man apidox aktiviert, doch es ist auch möglich die Arbeit aufzuteilen: Du schreibst die apidox selber und fragst den Originalautor (mailto:groot@kde.org), diese für dein Modul zu aktivieren. Er verspricht (zunmindest in der englischsprachigen Originalversion) das dann zu tun.

== APIDOX in neuem Code schreiben ==

Wenn mann neuen Code schreibt und dabei apidox verwenden möchte, sollte man am besten KDevelop benutzen. Vernünftig konfiguriert kann dieses automatisch ein Grundgerüst für apidox einfügen, man muß dann nur noch die eigentlichen Beschreibungen einfügen. Und man muß sich nicht mehr mit apidox kommandos rumärgern.

Wenn man sich nicht in dieser günstigen Lage befindet, sollte die folgende Checkliste einen durch die schlimmsten Untiefen beim Schreiben von apidox führen:

'''1. Schreibe die apidox direkt mit dem Code zusammen'''

Wenn man es mit etwas Disziplin schafft, direkt beim Schreiben einer Funktion foo(), wo man sich sowieso Gedanken über den gewünschten Effekt machen muss, auch gleich an die apidox zu denken, spart man sich diese Zeit sicherlich später, wenn man nicht mehr mühsam herausfinden muss, was die Funktion foo() eigentlich machen soll.

Das heißt nicht, dass man es auf diese Art und Weise machen muss, doch es bietet sich an. Durch die apidox werden auch Entscheidungen bezüglich des Designs dokumentiert. Auch wird dokumentiert, was ein bestimmter Codeabschnitt eigentlich macht, unabhängig davon, was er aktuell tut. Das macht es möglich, unabhängig zu überprüfen, ob der Code das tut, wozu er geschrieben ist. Das liegt daran, dass es bereits in der apidox dokumentiert wurde.

'''2. Dokumentierte deine Header vollständig'''

Die Header sind das, was den Benutzern als erstes vom Code ins Auge springt (in diesem Zusammenhang sind Entwickler Benutzer, die Code wiederverwenden). Aus diesem Grund sollen sie vollständig sein, d.h. jede noch so kleine Struktur sollte im Header dokumentiert werden. Im Einzelnen:

*Jede Datei sollte einen Kommentar haben, der den Nutzen dieser Datei beschreibt. Das wird von den KDE Richtlinien sowieso vorgeschrieben -- am Anfang der Datei sollte einfach vermerkt werden, wofür die Datei gut ist und in groben Zügen, was sie definiert. Das sollte in einem /** @file */ Kommentar erfolgen.
* Jeder Namensraum (namespace) sollte einen Kommentar haben. Ein bestimmter Namensraum benötigt nur einmal im Quellcodebaum einen Kommentar, doch es kann nicht schaden ihn bei jedem Auftreten erneut zu beschreiben -- nur kurz sollte es sein. Diese Kommentare sind einfache apidox Kommentare zwischen /** und */; keine besonderen Befehle wie bei Dateien das @file Befehl. 
Man sollte nur sicherstellen, dass der Kommentar direkt vor dem Namensraum steht und nichts dazwischen steht. Das folgende Beispiel zeigt, wie es aussehen soll:
<code cppqt>/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */

namespace Ungulate {
</code>
:Im nächsten Beispiel hat jemand etwas Extracode zwischen den apidox Kommentar und den Namensraum, der dokumentiert werden soll, gebracht. Das könnte Doxygen zu Fehlern bringen (in diesem Fall ist es einfach den Fehler zu finden) oder die Dokumentation des Namensraum kann sich plötzlich auf etwas ganz anderes beziehen (dann ist der Fehler schwer zu finden).
<code cppqt>
/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */
class Mammal;
namespace Ungulate {
</code>
:There is not much you can do about this except to be watching when you insert code -- don't separate apidox from the thing they are documenting.
*Every class should have a comment. Classes are the important building blocks of your application or library, so this is one place where writing lots helps. Write down why the class exists. Write down what it is supposed to do. Give an example of how to use it. Explain how not to use it, or what prerequisites it has (for instance, lots of classes need a KInstance object, but don't document that explicitly). The same caveats apply as with namespace apidox: make sure the class follows its apidox immediately.
*Every method should have a comment explaining what it does and what the parameters are for. Method parameters should be documented using @param. Don't rely on the name of the method or the parameters to be fully self-documenting. Besides, writing these things down properly will trigger Doxygen errors if you change them in an incompatible way later -- and that is going to save you lots of time in finding source and binary incompatibilities and explaining to users why their code suddenly doesn't do what they expect (assuming it compiles at all). So good method apidox is an additional insurance against making bad changes. Same caveats apply.
*Every enumeration type should have a comment explaining what the enumeration is for, even if it's just /** Various constants */.
*Every enumeration value should have a comment too, to explain what it represents. Don't rely on the name of the enumeration value being sufficiently expressive. For the purposes of readability, I suggest that you document enumeration values after the value, as opposed to the documentation format for namespaces, classes and methods where you write the documentation in front of the thing you are documenting. The format of the documentation is slightly different. Instead of writing /** Documentation */ in front, you write /**< Documentation afterards */, where the < denotes that the documentation applies to the thing just past. It looks like this:
<code cppqt>
enum State {
none, /**< No bracket seen */
bracket, /**< Found a ( for grouping */
squote, /**< Found a single quote */
dquote /**< Found double quotes */
};
</code>

'''3. Watch this space!'''

Watch the [http://www.englishbreakfastnetwork.org/ English Breakfast Network] for the [http://www.englishbreakfastnetwork.org/apidocs/ results] of your apidox work. Check the log files for errors -- Doxygen can complain quite loudly.

'''4. Write a main page for your application.'''

This is usually done in a separate file {{path|Mainpage.dox}} in the top-level of a library or application. The file's content is just a single apidox comment that starts with /** @mainpage title ; the rest of the file is just a long comment about what the library or application is for.

== APIDOX in altem Code korrigieren ==

Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)

In old apidox, you are more likely to suffer from the following symptoms:

*Missing parameter documentation (because parameters were renamed, or added, or removed, or something).
*Missing method documentation.
*Missing class documentation.
*Documentation that has wandered off on its own and is attached to the wrong thing now.

The first of these can be fixed by correcting the parameter documentation. See the examples section. The next two -- missing documentation that you can see is there in the source files but that does not show up in the generated HTML pages, is usually a matter of missing documentation on surrounding blocks. See the common pitfalls section, and make sure that the surrounding classes, namespaces and files all have documentation.

The last problem can best be fixed by moving the offending documentation back to where it belongs (really, it's not the documentation that is at fault, it's whatever has squeezed in -- the home-breaker -- between the documentation and the thing it was originally attached to). You could use some Doxygen special tags to avoid moving stuff around like that, but it does not help the understandability of the source much.

== Beispiel APIDOX ==

So what does documentation look like in the headers? How do you write a method documenation that describes the parameters as well? This section contains boilerplate for most common situations. Doxygen does not require a strict style -- it will ignore whitespace and asterisks at the beginning of a line, so you can make the documentation ASCII-pretty.

'''Documentation for a file:''' The newline after @file is significant! The text after @author is listed in a special Authors section of the apidox; you can list multiple authors.

<code cppqt>
/** @file
* This file is part of AnApplication and defines
* classes Ungulate and Moose.
*
* @author Mostly by me
*/
</code>

'''Documentation for a namespace:'''

<code cppqt>
/**
* This namespace collects functions related to
* counting and enumeration of mammals and their limbs.
*/
</code>

'''Documentation for a class:''' Some Doxygen special commands are used here to provide additional information. @author (as with files) identifies authors of the code; these are collected in a special ''Authors:'' section of the apidox. You can list more than one author. The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.

<code cppqt>
/**
* This class represents a Moose in the woodland
* simulator. A single Moose object can be created,
* but it is more useful to instantiate Moose::Factory
* by calling Moose::factory(), and then calling spawn()
* for each new Moose, since that maintains the ecological
* balance far better.
*
* @author Adriaan de Groot <degroot@kde.org>
* @since 3.5
*/
</code>

'''Method documentation:''' We can use @author and @since just like we do for classes. In addition, there are the parameters of the method that can be described. @p is used to refer to them in running text, and @param is used to construct a list of parameter descriptions that is specially formatted. Finally, @return entries describe the values that may be returned by the method.

<code cppqt>
/**
* This method names a particular Moose and as a side effect
* sets whether or not the Moose is treated as a Reindeer.
* When @p santa is @c true, the name of the moose is set to
* the next of the available Reindeer (if possible).
*
* @param name name to assign to the Moose, which is only
* relevant if the moose is not a Reindeer.
* @param santa is this Moose assigned to Santa? if so, the
* name is irrelevant.
*
* @return @c true if naming the Moose succeeded
* @return @c false if naming the Moose failed. This only
* happens if the Moose is assigned to Santa duty
* but there are already eight named Reindeer.
*/
bool name(const QString &name, bool santa = false);
</code>

Enum documentation is described in the section on writing new apidox. The same kind of documentation as for classes applies, with the addition of the documentation for each enumerated value which belongs inline.

== Beliebte Fehler ==

Dieser Abschnitt listet einige beliebte Fehler auf, die einem beim Schreiben der Apidox unterlaufen können. Typischerweise sind das leicht zu übersehende Fehler, die seltsame Fehlermeldungen produzieren, aber auch ein paar stilistische Fehler die vermieden werden sollten, werden angesprochen.

'''Fehlende APIDOX''': Man ''weiß'', dass man die dox für die Klasse "Moose" geschrieben hat, doch nach der Generierung ist sie nicht sichtbar. Man ''weiß'' auch, dass eine auf Dateiebene sichtbare Funktion int foo() dokumentiert wurde, doch die ist auch nicht da. Was geht hier vor?

Der häufigste Fehler, der zu "fehlender" apidox führt ist, zu vergessen, die umgebenden Strukturen zu dokumentieren. Die "Struktur" im Quellcode kommt von den Dateien, den Namensräumen, Klassen und Methoden. Um also eine Klasse zu dokumentieren muss man den Namensraum dokumentieren, in dem sie sich befinden (sofern es einen gibt) und die Datei in dem sie sich befindet. Um eine Methode zu dokumentieren, muss man die Klasse dokumentieren, in dem sie sich befindet (und so wiederum den Namensraum und die Datei). So die einfachste Daumenregel ist es, einfach ''alles'' zu dokumentieren.

{{note (de)|Diese Regel ist nicht ganz richtig: Klassen benötigen nicht, dass die Datei dokumentiert wird, in der sie sich befinden, aus diesem Grund kann man den /** @file */ Kommentar auslassen für Dateien, die nur Klassen und Namensräume beinhalten.
Beachte das Klassen in einem Namensraum erfordern, dass der Namensraum dokumentiert wird, doch Klassen im :: Namensraum benötigen keine Extradokumentation.
Etwas unklar ist das bei anonymen Namensräumen.

Für Funktionen in der Dateiebene, also Funktionen, die in einer Datei definiert werden und nicht in einem Namensraum oder einer Klasse ''muß'' die Datei, in der sie definiert ist, dokumentiert werden. Das gilt meistens für Dateien die eine Sammlung von nicht-Methoden Funktionen zur Verfügung stellen.}}

'''Broken parameter documentation:''' Documenting parameters to methods can be done two ways: you can document none of them, or you can document
''all'' of them for a given method. There is no middle ground (that doesn't
generate gobs of errors that you should fix).

If you document ''all'' of your parameters (which is a good thing to do,
and generates things in a nicely formatted fashion), then your method
apidox consists first of a general description of the method and then a
bunch of @param tags which describe each individual parameter. The @param
tag is followed by the name of the parameter -- watch out for spelling
and case-sensitivity! -- and then the description. The description can
span multiple lines.
<code cppqt>
/** Calculate the root-mean-square distance from the
* origin to the given integral coordinate.
*
* @param y y-coordinate, which is on an axis perpendicular to the
* x-axis, yet still in the same plane.
* @param x x-coordinate
*/
</code>

When you document all the parameters like this, Doxygen will complain if
you misspell parameter names, or forget some, or mention parameters that
are not there. This will force you to update the documentation if you
change the method signature. And that's a good thing.

Additional pitfalls are putting the type of the parameter in the list,
like @param int x, which makes "int" the name of the parameter. Another
pitfall is that @param should come after the general description.
Once the @param list starts, nothing can stop it except for other
list-style Doxygen tags like @since, @author or @return. So write @param
after the story and before, say, @return.

If you document ''none'' of the parameters, you do not use the @param tag
at all. You can talk about your parameters by writing @p before the name
of a parameter (or anything else, really, but it only makes sense in front
of a name of a parameter). Like this:
<code cppqt>
/** Calculate the root-mean-square distance from the origin to
* the given integral coordinate which is given as a pair @p x,
* @p y. If @p nonFree is true, use ESR instead of RMS in the
* computation.
*/
double distance(int x, int y, bool nonFree=false);
</code>

'''Misuse of tags in running text:''' This boils down to the warning
above about where to put @param: not every Doxygen tag can go anywhere.
Some start lists or basically end the general description part of a
description, so you need to avoid using them in running text.

'''Chosing between Doxygen errors and compiler warnings:''' If you are
going to document your parameters, you need to name them. If you are
defining a stub method, this can lead to compiler warnings.

'''Accidental tags:''' It can be easy to accidentally use Doxygen tags
in running text -- email addresses, backslash escapes, those are the
easy ones. Watch the Doxygen logs and escape that at sign with a backslash
when needed (i.e. write \@ to get an at sign). It's probably a good
idea to avoid the backslash style of apidox entirely; at the same time, if
you happen to write \moose, Doxygen will complain that that is an invalid
tag.

'''Accidental HTML:''' If you use < and > in your apidox, these may
confuse Doxygen -- especially if you write things like <service>
which look like HTML tags. This is a common way of writing some kind of
element that may be replaced in a method call or string or something, so
it crops up all the time. You know, you write some thing like this:
<code cppqt>
/** This method connects to a database. The connection string is
* composed of a username, password, host and database name as
* follows:
* <username>:<password>@<host>//<database>
*
* @return true if the connection succeeded.
*/
</code>

This bit of dox is terribly broken, because the whole sample connection
string will be interpreted as (bad) HTML and ignored. There are two
solutions:
<ol>
*Write \< instead of just < to escape the < and make Doxygen output it normally. Doxygen is smart enough to turn this into &lt; in HTML output. This has only a minimal impact on readability of the dox in the header files themselves.
*Use the HTML formatting that Doxygen makes available, and write ''foo'' instead of <foo>. This produces nicer output with italics instead of plain text, so it is easier to spot what is the replaceable part of the text. The downside is that it has a larger visible impact on the apidox in the headers.
</ol>

;Superfluous @ref
:It can be tempting -- certainly if you've written dox for other projects -- to use #method or @ref method to force a reference to another method somewhere. Relax, it's not needed and usually causes Doxygen warnings to boot. Just name the method normally, make apidox and watch the references appear naturally.

== KDE spezifische Tags ==
'''@bc''': Diese Markierung zeigte Binärkompatibilität an, ähnlich wie es ''@since'' tut. Das Argument hinter ''@bc'' zeigt den Bereich der Binärkompatibilität (zum Beispiel KDE4) an. Klassen, die nicht mit ''@bc'' markiert sind, können in einigen Modulen als inkompatibel markiert werden, damit sie vermieden werden.

Beispiel:
<code cpp>
/**
* This class emulates a Moose.
* @bc KDE4.2 Compatibility is expected to break
* with next-generation mooses.
*/
</code>

'''@libs''': Diese Markierung zeigt an, welche Bibliotheken mit einer bestimmten Klasse gelinkt werden sollen. Auch wenn es normalerweise der Name des Verzeichnisses ist, in dem sich die Klasse befinden, ist dies nicht immer der Fall.

Beispiel:
<code cpp>
/**
* This class emulates a Moose.
* @libs
* @a -lkdeui or use \$(LIB_KDEUI) in the KDE build framework.
*/
</code>

== Code Beispiele in APIDOX ==

Es kann nützlich sein, Beispielcode zur APIDOX einer Klasse hinzuzufügen. Sehr nützlich ist es auf jeden Fall für Leser, die sich fragen, wie man eine Klasse genau zu benutzen hat. Die meisten Klassen in {{path|kdelibs/kdecore}} haben Beispielcode.

Ein Weg, um Beispielcode zu schreiben ist es, @code und @endcode um den Block des Beispielcodes in den Doxygenkommentaren selber zu legen, wie im folgenden Beispiel:
<code cppqt>
/**
* This class represents a Moose.
* The correct way of generating Meese is to use the factory:
*
* @code
* Moose::Factory outlet = Moose::factory();
* Moose *m = outlet.spawn();
* @endcode
*/
</code>

Auf diese Art wird es in den meisten Beispielen in {{path|kdelibs}} gemacht. Das funktioniert auch ganz gut, man kann sich bei den Beispielen aufs wesentliche beschränken.

Ein wichtiges Problem dieser Herangehensweise um Beispielcode zu schreiben ist es, dass der Code niemals geprüft wird, ob er wirklich funktioniert. Die meisten Codebeispiele sind so gepackt, dass es schwer ist, diese in einen funktionsfähigen Code umzuschreiben, der wirklich kompiliert und läuft.

Um dieses Problem zu lösen, kann man ''richtigen Code'' schreiben, der wirklich kompiliert (als Teil dr Test-Suite für den Code, den man sowieso hat) und exakt beschreibt, wie eine Klasse in einem richtigen Programm benutzt werden soll. Man muß jedoch nicht den gesamten Code in die APIDOX übernehmen, sondern braucht nur die interessanten Teile zu markieren. Um das zu bewerkstelligen, wird eine Datei in das <tt>tests</tt> Unterverzeichnis eingefügt. Dann kann man das Doxygen @include-Tag benutzen, um den Code dieser Datei in die API Dokumentation zu übernehmen.

{{warning (de)|Benutze nicht @example! Es macht etwas total anderes als was du erwarten könntest (zum Beispiel fügt es keinen Beispiel-Code ein).}}

== Links ==

[http://www.stack.nl/~dimitri/doxygen/commands.html englische Liste der unterstützen Doxygen Tags]
:Hier ist eine Liste von allen verfügbaren Dokumentations-Tags von Doxygen von der offiziellen Seite. Beachte, das diese Seite ein Backslash vor einem Tag benutzt, während diese Seite immer das At-Zeichen benutzt. Beides ist erlaubt, doch in KDE sollte zu Gunsten der Konsistenz das At-Zeichen benutzt werden.

[[Category:Documentation]]

Development/Tutorials/API Documentation (de)

2008-11-30T15:38:40Z

DrSlowDecay: /* KDE spezifische Tags */ translated that part

{{Template:I18n/Language Navigation Bar|Development/Tutorials/API Documentation}}
__TOC__
{{Box|Definition|
'''API (''Application Programming Interface'') Dokumentation''' ist die Dokumentation eines ''Programmes'' und seiner Schnittstellen. Durch Dokumentation wird einem Entwickler, der mit oder an dem Programm arbeitet, erklärt, wie Dinge funktionieren und wie und welche Methoden aufzurufen sind.

API Dokumentation wird machmal auch API Referenz Handbuch (API reference manual) genannt. Es muß nicht ''nur'' ein Referenz Handbuch sein, obwohl es umfangreiches zusätzliches Material, wie Anleitungen, Zeitleisten, etc., enthalten kann. Auf dieser Seite wird alles Material welches die API eines Codes dokumentiert und erklärt "apidox" genannt.

Gute apidox benötigt etwas Mühe zum schreiben -- doch sicherlich weniger Mühe als gute ''Benutzer'' Dokumentation, da du als Entwickler für andere Entwickler schreibst und eklärst wie Code funktioniert und was er tun soll. So dein Publikum ist bereit damit zu arbeiten. Der Vorteil von apidox zeigt sich, wenn jemand anderes (oder sogar du selbst einige Monate später) den Code (wieder)verwenden oder erweitern möchte. Gute apidox bedeutet, dass jemand neues kommen kann, den Code schnell versteht und nützliche Patches erstellen kann. Gerade für Bibliotheken kann apidox es ermöglichen, diese wie eine Black Box zu benutzen (und so sollte es auch sein), da die benötigte Dokumentation vorliegt und die Dokumentation sich nicht in den tiefen des (vielleicht gar nicht vorliegenden) C codes befindet.|100%}}

== Vorwort ==

Mit APIDOX wird es anderen Entwicklern ermöglicht, auf ein Programm zuzugreifen. Sie sind nicht unbedingt notwenig doch sie helfen neuen Leuten, die an dem Programm arebeiten möchten oder den Code ohne große Änderungen wiederverwenden möchten, sicherlich eine Menge.

Ein Blick auf [http://doc.trolltech.com/latest/ die Qt Dokumentation (englisch)] ermöglicht es, einen Eindruck von guter apidox Dokumentation zu bekommen. Dort sieht man eine Stilkonsistenz, die sich durch die gesamte Dokumentation zieht. Dadurch kann man eine Menge über Qt lernen, nur indem man die Dokumentation liest. Es ist nicht notwendig, die Anleitungsprogramme auszuführen oder den Quellcode zu lesen um herauszufinden, was ein Parameter in einer bestimmten Methode einer Bibliothek macht. Es wird alles bereits erläutert.

Apidox zu schreiben besteht aus zwei Teilen. Der erste Teil ist technischer Natur: Man muß den Code verstehen, der dokumentiert werden soll, oder zumindest wissen, was er tun soll und wie er benutzt werden muss. Der andere Teil ist reine Disziplin: apidox ist am nützlichsten, wenn es sorgfältig und ausführlich benutzt wird.

Dieses Dokument versucht den apidox Prozess nicht zu ausführlich werden zu lassen, indem es einige dirkekte Tips gibt, wie man apidox schreibt. Es gibt dann doch die [[Policies/Library Documentation Policy|library apidox policies (englisch)]], die sehr viel strenger sind. Es schadet nicht, auch dort mal einen Blick reinzuwerfen.

{{note (de)|Die eigentliche Beispieldokumentation auf dieser Seite wird nicht übersetzt, da API Dokumentation in der Regel auf englisch verfasst werden, um eine internationale Mitarbeit zu ermöglichen}}

== APIDOX Basics ==

APIDOX werden durch das [http://www.doxygen.org Doxygen] Dokumentationswerkzeug verarbeitet. Dieses Werkzeug liest den Quellcode der Applikation (oder Bibliothek) und erzeugt schön formatierte Dokumentation daraus. Es gibt ein gutes [http://www.stack.nl/~dimitri/doxygen/manual.html Referenz Handbuch (auf englisch)] -- doch für die Grundlagen muß dieses nicht vollständig gelesen werden.

{{Tip|Doxygen muß für die Arbeit an apidox der Applikation nicht installiert sein. Alle paar Stunden erzeugt das [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] apidox für alle bekannten KDE Module. Logfiles und die eigentlichen Apidox werden ebenfalls bereitgestellt, um Fehlermeldungen zu entdecken und diese zu beheben. Das ist zwar nicht die schellste Methode apidox zu schreiben und zu korrigieren, doch es erledigt diese Aufgabe. Ein paar Stunden Arbeit am Tag, um an der apidox zu arbeiten, reichen aus.}}

{{Tip|Hast du Doxygen installiert und möchtest die apidox erzeugen, benutze das kdedoxygen.sh Skript wie es in [[Development/Tools/apidox|apidox (englisch)]] beschrieben ist.}}

Die Grundlagen von apidox sind einfach und machen Spaß: Man schreibt einfach Kommentare in den Code, die erklären wofür dieser ist. Diese Kommetare sind fast das gleiche wie das, was man sowieso in die header des Codes schreiben muß, so ist das ganze also nicht so schwer.

APIDOX werden in speziellen Kommentaren geschrieben. Diese Kommentare starten mit /** (Schrägstrich, Stern, Stern) -- und das ist es, was sie besonders macht. Der Rest des Kommentars ist einfacher Text, der den Teil des Programms beschreibt. Dieser Text wird vom Doxygen Prozessor interpretiert, damit dadurch passende Beschreibungen der Parameter und Rückgabewerte erfolgen kann. Doch die Dokumentation ist recht unkompliziert: Man schreibt einfach, was eine Methode tut innerhalb von /** und */, so wie folgendes Beispiel:

<code cppqt>
/** This method increases the sexyness of Kontact and should as
* such be called whenever possible (i.e. instead of having idle
* time, you might think of calling this method and helping
* Kontact gain even more popularity). You might even insert it
* into your own event loop to ensure it is called as often as
* possible. If these calls decrease the number of new features,
* it's still no problem to call it.
*/
void incSexyness(KInstance *instance);
</code>

Für eine vernünftige apidox muß jedes "Ding" des Programms dokumentiert werden. "Dinge" sind hierbei Verzeichnisse, Dateien, Namensräume, Klassen, Methoden, Aufzählungen und Variablen. Man kann eventuell Dateien und Verzeichnisse auslassen und sich nur auf die letzteren Punkte konzentrieren. Komplette apidox sehen ungefähr so aus:

<code cppqt>
/** Namespace for KDE network-related classes */
namespace KDENetwork {
/** Wrapper for a TCP/IP socket */
class Socket {
public:
/** Constructor. Calls listen() on some random high port. */
Socket();
private:
int fd;
};
}
</code>

Wie man sieht, ist jede Schachtelungsebene der eben erwähnten "Dinge" mit einem Kommentar versehen -- Der Namensraum, die Klasse und die Methode. Private "Dinge" benötigen keine apidox, protected "Dinge" jedoch schon.

Es ist wichtig, jede einzelne Schachtelungsebene zu dokumentieren, denn läßt man einen Ebene aus, ignoriert Doxygen die inneren ebenso und man findet diese nicht mehr wieder. Angenommen man würde im obigen Beispiel die Klassendokumentation weglassen, dann würde die Dokumentation für die Methode Socket() ebenfalls verschwinden. Das ist eine der typischen Fallen beim Schreiben von apidox.

Und wenn man nur eine Erklärung für jeden Teil seines Programmes schreibt, hat man schon einen großen Teil des Weges zu einer kompletten apidox hinter sich gelassen. Diese Erklärungen zu schreiben macht das Programm einfacher für andere Entwickler zu verstehen und zeigt einem oft schon sub-optimale Designs oder Namenswahlen. Auf diese Art gewinnen beide Seiten.

Man findet in der Liste von unterstützen Tags auch Beispiele für ausgefallenere apidox -- Erklärung von Parametern oder wie man die apidox mit Beispielen und Personendaten versieht. Es lohnt sich auch nachzusehen, wie man apidox aktiviert, doch es ist auch möglich die Arbeit aufzuteilen: Du schreibst die apidox selber und fragst den Originalautor (mailto:groot@kde.org), diese für dein Modul zu aktivieren. Er verspricht (zunmindest in der englischsprachigen Originalversion) das dann zu tun.

== APIDOX in neuem Code schreiben ==

Wenn mann neuen Code schreibt und dabei apidox verwenden möchte, sollte man am besten KDevelop benutzen. Vernünftig konfiguriert kann dieses automatisch ein Grundgerüst für apidox einfügen, man muß dann nur noch die eigentlichen Beschreibungen einfügen. Und man muß sich nicht mehr mit apidox kommandos rumärgern.

Wenn man sich nicht in dieser günstigen Lage befindet, sollte die folgende Checkliste einen durch die schlimmsten Untiefen beim Schreiben von apidox führen:

'''1. Schreibe die apidox direkt mit dem Code zusammen'''

Wenn man es mit etwas Disziplin schafft, direkt beim Schreiben einer Funktion foo(), wo man sich sowieso Gedanken über den gewünschten Effekt machen muss, auch gleich an die apidox zu denken, spart man sich diese Zeit sicherlich später, wenn man nicht mehr mühsam herausfinden muss, was die Funktion foo() eigentlich machen soll.

Das heißt nicht, dass man es auf diese Art und Weise machen muss, doch es bietet sich an. Durch die apidox werden auch Entscheidungen bezüglich des Designs dokumentiert. Auch wird dokumentiert, was ein bestimmter Codeabschnitt eigentlich macht, unabhängig davon, was er aktuell tut. Das macht es möglich, unabhängig zu überprüfen, ob der Code das tut, wozu er geschrieben ist. Das liegt daran, dass es bereits in der apidox dokumentiert wurde.

'''2. Dokumentierte deine Header vollständig'''

Die Header sind das, was den Benutzern als erstes vom Code ins Auge springt (in diesem Zusammenhang sind Entwickler Benutzer, die Code wiederverwenden). Aus diesem Grund sollen sie vollständig sein, d.h. jede noch so kleine Struktur sollte im Header dokumentiert werden. Im Einzelnen:

*Jede Datei sollte einen Kommentar haben, der den Nutzen dieser Datei beschreibt. Das wird von den KDE Richtlinien sowieso vorgeschrieben -- am Anfang der Datei sollte einfach vermerkt werden, wofür die Datei gut ist und in groben Zügen, was sie definiert. Das sollte in einem /** @file */ Kommentar erfolgen.
* Jeder Namensraum (namespace) sollte einen Kommentar haben. Ein bestimmter Namensraum benötigt nur einmal im Quellcodebaum einen Kommentar, doch es kann nicht schaden ihn bei jedem Auftreten erneut zu beschreiben -- nur kurz sollte es sein. Diese Kommentare sind einfache apidox Kommentare zwischen /** und */; keine besonderen Befehle wie bei Dateien das @file Befehl. 
Man sollte nur sicherstellen, dass der Kommentar direkt vor dem Namensraum steht und nichts dazwischen steht. Das folgende Beispiel zeigt, wie es aussehen soll:
<code cppqt>/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */

namespace Ungulate {
</code>
:Im nächsten Beispiel hat jemand etwas Extracode zwischen den apidox Kommentar und den Namensraum, der dokumentiert werden soll, gebracht. Das könnte Doxygen zu Fehlern bringen (in diesem Fall ist es einfach den Fehler zu finden) oder die Dokumentation des Namensraum kann sich plötzlich auf etwas ganz anderes beziehen (dann ist der Fehler schwer zu finden).
<code cppqt>
/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */
class Mammal;
namespace Ungulate {
</code>
:There is not much you can do about this except to be watching when you insert code -- don't separate apidox from the thing they are documenting.
*Every class should have a comment. Classes are the important building blocks of your application or library, so this is one place where writing lots helps. Write down why the class exists. Write down what it is supposed to do. Give an example of how to use it. Explain how not to use it, or what prerequisites it has (for instance, lots of classes need a KInstance object, but don't document that explicitly). The same caveats apply as with namespace apidox: make sure the class follows its apidox immediately.
*Every method should have a comment explaining what it does and what the parameters are for. Method parameters should be documented using @param. Don't rely on the name of the method or the parameters to be fully self-documenting. Besides, writing these things down properly will trigger Doxygen errors if you change them in an incompatible way later -- and that is going to save you lots of time in finding source and binary incompatibilities and explaining to users why their code suddenly doesn't do what they expect (assuming it compiles at all). So good method apidox is an additional insurance against making bad changes. Same caveats apply.
*Every enumeration type should have a comment explaining what the enumeration is for, even if it's just /** Various constants */.
*Every enumeration value should have a comment too, to explain what it represents. Don't rely on the name of the enumeration value being sufficiently expressive. For the purposes of readability, I suggest that you document enumeration values after the value, as opposed to the documentation format for namespaces, classes and methods where you write the documentation in front of the thing you are documenting. The format of the documentation is slightly different. Instead of writing /** Documentation */ in front, you write /**< Documentation afterards */, where the < denotes that the documentation applies to the thing just past. It looks like this:
<code cppqt>
enum State {
none, /**< No bracket seen */
bracket, /**< Found a ( for grouping */
squote, /**< Found a single quote */
dquote /**< Found double quotes */
};
</code>

'''3. Watch this space!'''

Watch the [http://www.englishbreakfastnetwork.org/ English Breakfast Network] for the [http://www.englishbreakfastnetwork.org/apidocs/ results] of your apidox work. Check the log files for errors -- Doxygen can complain quite loudly.

'''4. Write a main page for your application.'''

This is usually done in a separate file {{path|Mainpage.dox}} in the top-level of a library or application. The file's content is just a single apidox comment that starts with /** @mainpage title ; the rest of the file is just a long comment about what the library or application is for.

== APIDOX in altem Code korrigieren ==

Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)

In old apidox, you are more likely to suffer from the following symptoms:

*Missing parameter documentation (because parameters were renamed, or added, or removed, or something).
*Missing method documentation.
*Missing class documentation.
*Documentation that has wandered off on its own and is attached to the wrong thing now.

The first of these can be fixed by correcting the parameter documentation. See the examples section. The next two -- missing documentation that you can see is there in the source files but that does not show up in the generated HTML pages, is usually a matter of missing documentation on surrounding blocks. See the common pitfalls section, and make sure that the surrounding classes, namespaces and files all have documentation.

The last problem can best be fixed by moving the offending documentation back to where it belongs (really, it's not the documentation that is at fault, it's whatever has squeezed in -- the home-breaker -- between the documentation and the thing it was originally attached to). You could use some Doxygen special tags to avoid moving stuff around like that, but it does not help the understandability of the source much.

== Beispiel APIDOX ==

So what does documentation look like in the headers? How do you write a method documenation that describes the parameters as well? This section contains boilerplate for most common situations. Doxygen does not require a strict style -- it will ignore whitespace and asterisks at the beginning of a line, so you can make the documentation ASCII-pretty.

'''Documentation for a file:''' The newline after @file is significant! The text after @author is listed in a special Authors section of the apidox; you can list multiple authors.

<code cppqt>
/** @file
* This file is part of AnApplication and defines
* classes Ungulate and Moose.
*
* @author Mostly by me
*/
</code>

'''Documentation for a namespace:'''

<code cppqt>
/**
* This namespace collects functions related to
* counting and enumeration of mammals and their limbs.
*/
</code>

'''Documentation for a class:''' Some Doxygen special commands are used here to provide additional information. @author (as with files) identifies authors of the code; these are collected in a special ''Authors:'' section of the apidox. You can list more than one author. The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.

<code cppqt>
/**
* This class represents a Moose in the woodland
* simulator. A single Moose object can be created,
* but it is more useful to instantiate Moose::Factory
* by calling Moose::factory(), and then calling spawn()
* for each new Moose, since that maintains the ecological
* balance far better.
*
* @author Adriaan de Groot <degroot@kde.org>
* @since 3.5
*/
</code>

'''Method documentation:''' We can use @author and @since just like we do for classes. In addition, there are the parameters of the method that can be described. @p is used to refer to them in running text, and @param is used to construct a list of parameter descriptions that is specially formatted. Finally, @return entries describe the values that may be returned by the method.

<code cppqt>
/**
* This method names a particular Moose and as a side effect
* sets whether or not the Moose is treated as a Reindeer.
* When @p santa is @c true, the name of the moose is set to
* the next of the available Reindeer (if possible).
*
* @param name name to assign to the Moose, which is only
* relevant if the moose is not a Reindeer.
* @param santa is this Moose assigned to Santa? if so, the
* name is irrelevant.
*
* @return @c true if naming the Moose succeeded
* @return @c false if naming the Moose failed. This only
* happens if the Moose is assigned to Santa duty
* but there are already eight named Reindeer.
*/
bool name(const QString &name, bool santa = false);
</code>

Enum documentation is described in the section on writing new apidox. The same kind of documentation as for classes applies, with the addition of the documentation for each enumerated value which belongs inline.

== Beliebte Fehler ==

This section lists common pitfalls in writing apidox. Typically, they are easily
overlooked mistakes that produce weird error messages, but I will also include
some stylistic pitfalls that should be avoided.

'''Missing APIDOX''': You ''know'' you wrote dox for class Moose, but after
generation they are not visible. You ''know'' that the file-scope function int
foo() is documented, but it's not there either! What is going on?

The most common pitfall, the one that leads to "missing" apidox, is forgetting
to document surrounding structure. The "structure" in the source comes from
files, namespaces, classes and methods. In order to document a class you must
document the namespace it is in (if there is one) and the file that it is in.
In order to document a method, you must document the class it is in (and thus
the namespace and file). So the easiest rule of thumb is to
document ''everything''.
{{note (de)|This hard-and-fast rule is not quite accurate:
classes do not need the file to be documented,
so you can leave out the /** @file */ comment for
source files containing only classes (and namespaces).
Note that classes in a namespace require the namespace
to be documented, but classes in the :: namespace
don't need extra documentation.
I'm not sure about anonymous namespaces.

For file-scoped functions -- that is, functions
that are defined in a file, not in a namespace
and not in a class,
you ''must'' document the file
they are in. This applies mostly
to files which collect a bunch of non-method utility functions.}}

'''Broken parameter documentation:''' Documenting parameters to methods can be done two ways: you can document none of them, or you can document
''all'' of them for a given method. There is no middle ground (that doesn't
generate gobs of errors that you should fix).

If you document ''all'' of your parameters (which is a good thing to do,
and generates things in a nicely formatted fashion), then your method
apidox consists first of a general description of the method and then a
bunch of @param tags which describe each individual parameter. The @param
tag is followed by the name of the parameter -- watch out for spelling
and case-sensitivity! -- and then the description. The description can
span multiple lines.
<code cppqt>
/** Calculate the root-mean-square distance from the
* origin to the given integral coordinate.
*
* @param y y-coordinate, which is on an axis perpendicular to the
* x-axis, yet still in the same plane.
* @param x x-coordinate
*/
</code>

When you document all the parameters like this, Doxygen will complain if
you misspell parameter names, or forget some, or mention parameters that
are not there. This will force you to update the documentation if you
change the method signature. And that's a good thing.

Additional pitfalls are putting the type of the parameter in the list,
like @param int x, which makes "int" the name of the parameter. Another
pitfall is that @param should come after the general description.
Once the @param list starts, nothing can stop it except for other
list-style Doxygen tags like @since, @author or @return. So write @param
after the story and before, say, @return.

If you document ''none'' of the parameters, you do not use the @param tag
at all. You can talk about your parameters by writing @p before the name
of a parameter (or anything else, really, but it only makes sense in front
of a name of a parameter). Like this:
<code cppqt>
/** Calculate the root-mean-square distance from the origin to
* the given integral coordinate which is given as a pair @p x,
* @p y. If @p nonFree is true, use ESR instead of RMS in the
* computation.
*/
double distance(int x, int y, bool nonFree=false);
</code>

'''Misuse of tags in running text:''' This boils down to the warning
above about where to put @param: not every Doxygen tag can go anywhere.
Some start lists or basically end the general description part of a
description, so you need to avoid using them in running text.

'''Chosing between Doxygen errors and compiler warnings:''' If you are
going to document your parameters, you need to name them. If you are
defining a stub method, this can lead to compiler warnings.

'''Accidental tags:''' It can be easy to accidentally use Doxygen tags
in running text -- email addresses, backslash escapes, those are the
easy ones. Watch the Doxygen logs and escape that at sign with a backslash
when needed (i.e. write \@ to get an at sign). It's probably a good
idea to avoid the backslash style of apidox entirely; at the same time, if
you happen to write \moose, Doxygen will complain that that is an invalid
tag.

'''Accidental HTML:''' If you use < and > in your apidox, these may
confuse Doxygen -- especially if you write things like <service>
which look like HTML tags. This is a common way of writing some kind of
element that may be replaced in a method call or string or something, so
it crops up all the time. You know, you write some thing like this:
<code cppqt>
/** This method connects to a database. The connection string is
* composed of a username, password, host and database name as
* follows:
* <username>:<password>@<host>//<database>
*
* @return true if the connection succeeded.
*/
</code>

This bit of dox is terribly broken, because the whole sample connection
string will be interpreted as (bad) HTML and ignored. There are two
solutions:
<ol>
*Write \< instead of just < to escape the < and make Doxygen output it normally. Doxygen is smart enough to turn this into &lt; in HTML output. This has only a minimal impact on readability of the dox in the header files themselves.
*Use the HTML formatting that Doxygen makes available, and write ''foo'' instead of <foo>. This produces nicer output with italics instead of plain text, so it is easier to spot what is the replaceable part of the text. The downside is that it has a larger visible impact on the apidox in the headers.
</ol>

;Superfluous @ref
:It can be tempting -- certainly if you've written dox for other projects -- to use #method or @ref method to force a reference to another method somewhere. Relax, it's not needed and usually causes Doxygen warnings to boot. Just name the method normally, make apidox and watch the references appear naturally.

== KDE spezifische Tags ==
'''@bc''': Diese Markierung zeigte Binärkompatibilität an, ähnlich wie es ''@since'' tut. Das Argument hinter ''@bc'' zeigt den Bereich der Binärkompatibilität (zum Beispiel KDE4) an. Klassen, die nicht mit ''@bc'' markiert sind, können in einigen Modulen als inkompatibel markiert werden, damit sie vermieden werden.

Beispiel:
<code cpp>
/**
* This class emulates a Moose.
* @bc KDE4.2 Compatibility is expected to break
* with next-generation mooses.
*/
</code>

'''@libs''': Diese Markierung zeigt an, welche Bibliotheken mit einer bestimmten Klasse gelinkt werden sollen. Auch wenn es normalerweise der Name des Verzeichnisses ist, in dem sich die Klasse befinden, ist dies nicht immer der Fall.

Beispiel:
<code cpp>
/**
* This class emulates a Moose.
* @libs
* @a -lkdeui or use \$(LIB_KDEUI) in the KDE build framework.
*/
</code>

== Code Beispiele in APIDOX ==

Es kann nützlich sein, Beispielcode zur APIDOX einer Klasse hinzuzufügen. Sehr nützlich ist es auf jeden Fall für Leser, die sich fragen, wie man eine Klasse genau zu benutzen hat. Die meisten Klassen in {{path|kdelibs/kdecore}} haben Beispielcode.

Ein Weg, um Beispielcode zu schreiben ist es, @code und @endcode um den Block des Beispielcodes in den Doxygenkommentaren selber zu legen, wie im folgenden Beispiel:
<code cppqt>
/**
* This class represents a Moose.
* The correct way of generating Meese is to use the factory:
*
* @code
* Moose::Factory outlet = Moose::factory();
* Moose *m = outlet.spawn();
* @endcode
*/
</code>

Auf diese Art wird es in den meisten Beispielen in {{path|kdelibs}} gemacht. Das funktioniert auch ganz gut, man kann sich bei den Beispielen aufs wesentliche beschränken.

Ein wichtiges Problem dieser Herangehensweise um Beispielcode zu schreiben ist es, dass der Code niemals geprüft wird, ob er wirklich funktioniert. Die meisten Codebeispiele sind so gepackt, dass es schwer ist, diese in einen funktionsfähigen Code umzuschreiben, der wirklich kompiliert und läuft.

Um dieses Problem zu lösen, kann man ''richtigen Code'' schreiben, der wirklich kompiliert (als Teil dr Test-Suite für den Code, den man sowieso hat) und exakt beschreibt, wie eine Klasse in einem richtigen Programm benutzt werden soll. Man muß jedoch nicht den gesamten Code in die APIDOX übernehmen, sondern braucht nur die interessanten Teile zu markieren. Um das zu bewerkstelligen, wird eine Datei in das <tt>tests</tt> Unterverzeichnis eingefügt. Dann kann man das Doxygen @include-Tag benutzen, um den Code dieser Datei in die API Dokumentation zu übernehmen.

{{warning (de)|Benutze nicht @example! Es macht etwas total anderes als was du erwarten könntest (zum Beispiel fügt es keinen Beispiel-Code ein).}}

== Links ==

[http://www.stack.nl/~dimitri/doxygen/commands.html englische Liste der unterstützen Doxygen Tags]
:Hier ist eine Liste von allen verfügbaren Dokumentations-Tags von Doxygen von der offiziellen Seite. Beachte, das diese Seite ein Backslash vor einem Tag benutzt, während diese Seite immer das At-Zeichen benutzt. Beides ist erlaubt, doch in KDE sollte zu Gunsten der Konsistenz das At-Zeichen benutzt werden.

[[Category:Documentation]]

Development/Tutorials/Sensors

2008-11-30T14:25:32Z

DrSlowDecay: Added language navigation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Sensors}}

Implementing KSysGuard sensors simple example.

Prerequisities: KDE, Perl.

Imagine you have a program that monitors some value important for you.
You want the value to be plotted or displayed in the KDE systray.

The most straightforward way is to add it to KSysGuard as a sensor.

== Example ==

Step 1. Create, for example, "/home/vi/code/sensor/sensor.pl" with the following content:
<code lang="perl">#!/usr/bin/perl -w
$|=1;

print "ksysguardd 1.2.0\n";
print "ksysguardd> ";

while(<>){
if(/monitors/){
print "random\tinteger\n";
}
if(/random/){
if(/\?/){
print "Random Value\t0\t100\n";
}else{
print int(rand()*100),"\n";
}
}
print "ksysguardd> ";
}
</code>

Step 2: Launch KSysGuard, File->Connect Host->Custom Command, enter "/home/vi/code/sensor/sensor.pl" in the Command field, OK.

Step 3: Open "127.0.0.1", find "random Integer Value", drag it to some sheet.

You will see your sensor (random value from 0 to 100 in this case).

== Systray ==

If you want to see the plot is your systray, follow this:

Step 1: Add "KSysGuard applet to the desktop".

Step 2: In there's no spare displays, choose "Configure System Guard" in the context menu of the applet and increase "Number of displays".

Step 3: Launch KSysGuard, follow previous example to get access to your sensor.

Step 4: Drag and drop from "random Integer Value" to the free display in the systray.

Step 5: "Signal plotter", then you will be asked again to provide the data source. Choose "Custom Command" with the same script.

[Step 6: Open properties and remove grids and lines to clean up the plot]

== Protocol ==

The ksysguardd protocol:
1. Server sends version line ("ksysguardd 1.2.0") ended with newline.
2. Server sends "ksysguardd> " with spacebar and without newline.
Available commands:
monitors -- List available sensors
<sensor name> -- Get the value of some sensor
<sensor name>? -- Get the metadata of the sensor

"monitor" command:
For each sensor, send the sensor name TAB the sensor type (integer) NEWLINE.
Then go back to the prompt "ksysguardd> ".

get command:
For integer sensors, server should send one integer value and NEWLINE.

info command:
Server should send the Display Name of the sensor TAB minimum value TAB maximum value TAB units NEWLINE. Looks like this command or some part of it is optional.

== Example session ==

Example of session:
<code>
ksysguardd 1.2.0
ksysguardd> random
96
ksysguardd> random
46
ksysguardd> monitors
random.integer
ksysguardd> random
11
ksysguardd> random?
Random Value.0.100
ksysguardd> random
47
ksysguardd> random
54
ksysguardd> random
5
ksysguardd> random
37
ksysguardd> random
41
ksysguardd> random
58
ksysguardd> random
36
ksysguardd> random
69
ksysguardd> random
83
ksysguardd>
</code>

Development/Tutorials/KPixmapCache

2008-11-30T14:22:45Z

DrSlowDecay: Added language navigation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KPixmapCache}}
== Introduction ==
{{class|KPixmapCache}} provides disk-caching of QPixmaps. If you're using SVGs or generating pixmaps from some data, you might consider using it as it eliminates the need to generate the same pixmaps over and over again.

== Using it ==
=== Creating the cache object ===
It's API is similar to that of the QPixmapCache.
To use it, you first need to create the cache object, using a unique name:
<code cppqt>
KPixmapCache* cache = new KPixmapCache("myapp-images");
</code>

=== Inserting and finding pixmaps ===
Once that is done you can easily retrieve and insert images with insert() and find() methods:
<code cppqt>
QPixmap pix("file1.png");
cache->insert("file1.png", pix);

QPixmap pix2;
if (cache->find("file2.png", pix2)) {
// The pixmap was loaded from cache.
} else {
// Pixmap was not found in the cache.
// Load and insert it:
pix2 = QPixmap("file2.png");
cache->insert("file2.png", pix2);
}
</code>

=== The Easy Way ===
As loading pixmaps from files with the aid of cache is a very common operation, KPixmapCache provides a convenience method for that:
<code cppqt>
QString filename("myfile.png");
QPixmap pix = cache->loadFromFile(filename);
</code>
This first checks if the given file is in the cache. If it is, it's loaded from the cache, otherwise it's loaded from the file and inserted into cache.

Similar method is provided for loading SVG files:
<code cppqt>
QString filename("myfile.svg");
QPixmap pix = cache->loadFromSVG(filename);
</code>
This renders contents of the SVG file onto pixmap, using SVG's default size by default. If you need a different size, you can specify it as the second argument of that method:
<code cppqt>
QString filename("myfile.svg");
QSize size(150, 250);
QPixmap pix = cache->loadFromSVG(filename, size);
</code>
This renders the SVG onto a pixmap with the size of 150x250 pixels.

=== Timestamps ===
Often you need to make sure the cache is up-to-date and you're not using obsolete pixmaps. For this, the cache provides timestamp() method. By default it returns time when the cache was created, but you can set your own timestamp with setTimestamp() method.

<code cppqt>
// Our data
MyDataObject data;
// Make sure the cache is up to date
if (cache->timestamp() < data.timestamp()) {
// Data is newer than the cache
// Thus the cache is obsolete, delete and reinitialize it
cache->discard();
}
// Here the cache is always recent enough
QPixmap visualizedData;
QString key("data-visualization");
// Try to find the visualization from the cache
if (!cache->find(key, visualizedData)) {
// Visualization is not in the cache, recreate it...
visualizedData = createVisualization(data);
// ...and put the resulting image into cache
cache->insert(key, visualizedData);
}
// Show the visualizedData pixmap to user
</code>
This example creates a visual representation of some data. If the data is more recent than the cache, then contents of the cache are deleted using the discard() method. Next, we check if cache already contains the necessary pixmap. If it does, then there is no need to recreate it from the data (which might be expensive).

=== API docs ===
For a list of all KPixmapCache methods, check out its [http://api.kde.org/classmapper.php?class=KPixmapCache&module=kdelibs&version=4.0 API docs].

Getting Started/Build/KDE4.x

2008-11-30T14:19:56Z

DrSlowDecay: Added language navigation

{{Template:I18n/Language Navigation Bar|Getting_Started/Build/KDE4.x}}

==Objectives==

You probably want to keep your current KDE-3.5.x installation till you feel that KDE-4.x.y meets your needs for actual day to day use of your computer. Yet, you want to be able to change over with a minimum of work when the time comes to make the switch.

==Method==

The best way to accomplish this is to install the needed support libraries on your system in the usual manner. Convention is that these should be installed in the /usr/local/ directory. By default, Troll Tech installs Qt in: /usr/local/Trolltech/Qt-4/. It is best to install KDE-4.x.y in its own directory so that the directory can be deleted if some large problem occurs. I will be using /usr/local/KDE-4/ but you can call it whatever you want.

We will keep configurations straight by using a separate user account for accessing KDE-4.x.y. This user account will contain your configurations of KDE-4.x.y and will have a script to set the environment variables (.bash_profile if using Linux).

==Installation==

=== Required packages from your distribution===
* [[Getting_Started/Build/KDE4/LFS|Linux from Scratch]] or to build from source.

(Till other distro instructions are added, you can probably determine the correct version to install by reading the LFS list of libraries)

'''DO NOT build the Strigi version for KDE4 TRUNK''' for KDE-4.1

If you have trouble building 4.1.1 or 4.1 BRANCH >= r852727, use the Strigi-0.5.10 release or, if using SVN, make certain that the revision number for the Strigi-0.5 BRANCH is >= 854542

'''DO NOT build the versions for KDE4 TRUNK''' for KDE-4.0

KDE-4.0: You need to have the correct versions for: Qt, Soprano, & QImageBlitz.

===Create the User Account===

Use whatever method you wish to create a new user account. Mine is called: "KDE4". Then edit or create the user specific login script (.bash_profile for Linux). There is a lot that goes into this. Note that this presumes that USER was correctly set by the system login script.

<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>

:<nowiki>#</nowiki> Redundant setting of HOME as work around for Bash bug

:HOME=/home/KDE4
:PATH=$HOME/bin:<nowiki>$</nowiki>PATH
:export PATH HOME

:XDG_DATA_HOME="$HOME/.local/share"
:XDG_CONFIG_HOME="$HOME/.config"
:export XDG_DATA_HOME XDG_CONFIG_HOME

:KDEDIR=/usr/local/KDE-4
:KDEHOME=$HOME/.kde4
:KDETMP=/tmp/$USER-kde4
:mkdir -p $KDETMP
:KDEVARTMP=/var/tmp/$USER-kde4
:mkdir -p $KDEVARTMP
:KDEDIRS=$KDEDIR
:PKG_CONFIG_PATH=/usr/local/KDE-4/lib/pkgconfig:$PKG_CONFIG_PATH
:export KDEDIR KDEHOME KDETMP KDEVARTMP KDEDIRS PKG_CONFIG_PATH

:QTDIR=/usr/local/Trolltech/Qt-4
:QT_PLUGIN_PATH=$KDEDIR/lib/kde4/plugins:$QT_PLUGIN_PATH
:PKG_CONFIG_PATH=$QTDIR/lib/pkgconfig:$PKG_CONFIG_PATH
:export QTDIR QT_PLUGIN_PATH PKG_CONFIG_PATH

:PATH=$QTDIR/bin:$KDEDIR/bin:$PATH
:export PATH

:XDG_CONFIG_DIRS=/usr/local/KDE-4/etc/xdg
:XDG_DATA_DIRS=$KDEDIR/share

:export XDG_CONFIG_DIRS XDG_DATA_DIRS

:LD_LIBRARY_PATH=$QTDIR/lib:$KDEDIR/lib
:export LD_LIBRARY_PATH

:LIBXCB_ALLOW_SLOPPY_LOCK="true"
:export LIBXCB_ALLOW_SLOPPY_LOCK

<nowiki>------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------8<------</nowiki>

This is in addition to other things that you need in the script which would probably go at the beginning -- this large block of junk is to be added at the end. The XDG directories might need to be modified for your system.

===Build===

To build, you must be logged on as the new user account (KDE4). You can 'su' for the whole thing or 'su -C' for each install.

Packages need to be installed with the correct prefixes for this to work:

:If you are building Qt from source, configure it with with --prefix=/usr/local/Trolltech/Qt-4. If you installed it from a binary, determine the prefix and change: QTDIR in the script above.

:KDE should use: -DCMAKE_INSTALL_PREFIX=/usr/local/KDE-4 when running cmake.

:KDE Support should installed in the same directory as KDE. This also applies to some of the packages if you are installing the individual packages/modules for a release or BRANCH. For packages that don't use CMake that would be: --prefix=/usr/local/KDE-4. The packages that don't install anything in "share" (eigen,eigen2) can be installed in "/usr/local/".

:Other packages should be installed with the default prefix (/usr/local).

Getting Started/Sources/Subversion (de)

2008-11-30T10:25:15Z

DrSlowDecay: finished translation

{{Template:I18n/Language Navigation Bar|Getting Started/Sources/Using Subversion with KDE}}

{{TutorialBrowser (de)|

series=Anfang|

name=Subversion mit KDE benutzen|
}}

== Zusammenfassung ==

Der folgende Text ist eine schnelle kde-spezifische Einführung, wie man Subversion benutzt, um auf Dateien und Software im KDE Repository zuzugreifen. Für einen vollständigen Überblick über die Fähigkeiten von Subversion verweisen wir auf das Buch "[http://svnbook.red-bean.com/ Version Control with Subversion (englisch)]".

== Am Anfang ==

Um das KDE Subversion Repository benutzen zu können, benötigen Sie zwei Dinge:

# Ein Subversion Client Programm
# Einen Zugang zu unserem Repository

Beachte: Für einen anonymen nur-lesen Zugriff benutzen Sie das Protokoll "svn", kein "yourname@" den Server "anonsvn.kde.org" statt dem unten genannten.

'''Subversion installieren:''' Eine Anleitung zur Installtion des Client Programms wird hier nicht gegeben. Sehen Sie in den Installtionsanleitungen Ihres Systems nach, um herauszufinden, wie man Subversion installiert. Sie benötigen mindesten Version 1.1. Wenn Sie Subversion selber compilieren und Sie auf das Repository per https (und nicht über svn+ssh) zugreifen wollen, benötigen Sie SSL und ZLIB Unterstützung und müssen daher die <tt>--with-ssl --with-zlib</tt> Option übergeben.

Alternativ können Sie auch einen der zahlreich vefügbaren graphischen Clients installieren. Diese Anleitung wendet sich an personen, die nur das <tt>svn</tt> Programm benutzen und bezieht sich dabei auf Dinge die mit dem alten <tt>cvs</tt> Programm erledigt wurden.

'''Ein Benutzerkonto bekommen:''' Hatten Sie vorher ein CVS Benutzerkonto, wurde dieses zum neuen Subversion Client migriert. Wenn nicht, sehen Sie in der [[Contribute/Get_a_SVN_Account|entsprechenden Anleitung]] nach, wie man eines bekommt.

{{Note (de)|Wenn Sie ihr CVS Passwort verloren haben, gibt es einfache Wege, dieses zu ermitteln. Benutzen Sie [http://ktown.kde.org/~coolo/cvspwd.c cvspwd.c] pder [http://kdab.net/~dfaure/cvs-unscramble cvs-unscramble] (Perl).}}

== Die Struktur des KDE Repository ==

svn.kde.org/home/kde

ist die Adresse des KDE Subversion Repositorys. Das Repository wird über das HTTPS oder SVN-SSH Protokoll angesrochen, was bedeutet, dass Ihr Passwort sicher gegenüber Abhörversuche dritter ist.

Der SSL certificate md5 fingerprint für die Repositorys ist:
F6BF EDE2 D016 D1B2 4F18 742E 2C8F B7EF

Der SSL certificate sha1 fingerprint für die Repositorys ist:
e1:e6:41:96:3c:eb:ae:78:e2:73:0d:a2:32:2f:6b:21:13:bf:3d:0f

Für Personen, die svn+ssh benutzen ist hier der Fingerprint des RSA Schlüssels des Servers:
86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb

Das Repository ist in Hauptverzeichnisse organisiert:

# /branches
# /tags
# /trunk

Man kann das Repository durchforgsten über [http://websvn.kde.org/ http://websvn.kde.org/]

=== Das Unterverzeichnis /trunk ===

Das <tt>/trunk</tt> Hauptunterverzeichnis ist dasjenige, in dem die Hauptentwicklung an KDE stattfindet. Was Sie hier finden, wird als nächstes als KDE und assoziierte Programme veröffentlicht. Hier finden Sie auch das <tt>www</tt> Modul, welches die Webpages rund um KDE beinhaltet.

<tt>/trunk</tt> ist unterteilt in folgende Unterverzeichnisse:

*<tt>KDE/</tt> KDE selber, welches die nächste Veröffentlichung werden wird. Es besteht aus folgenden Modulen:
**'''kdelibs''' - KDE Hauptbibliotheken, die von allen KDE Programmen benutzt werden
**'''kdebase''' - KDE Basisprogramme, wie das KDE Control Center, Plasma (die Oberfläche) und Konqueror (der Web Browser)
**'''kdeaccessibility''' - Accessibility Dateien
**'''kdeadmin''' - KDE Administrationsprogramme
**'''kdeartwork''' - Bilder, Themen, Sounds und andere künstlerische Dateien
**'''kdebindings''' - Bindungen für andere Sprache außer C++
**'''kdeedu''' - Erzieherische und Wissenschaftliche Programme für KDE
**'''kdegames''' - KDE Spiele
**'''kdegraphics''' - KDE Graphikapplicationen
**'''kdemultimedia''' - KDE Multimediaapplicationen
**'''kdenetwork''' - KDE Netzwerkapplicationen
**'''kdepim''' - KDE Personal Information Management Applicationen
**'''kdepimlibs''' - Biblotheken, die von KDE-PIM Applicationen benötigt werden.
**'''kdesdk''' - KDE Software Development Kit Applicationen
**'''kdetoys''' - KDE Spielzeug Applicationen
**'''kdeutils''' - Allgemeine KDE Werkzeuge
**'''kdevelop''' - Das KDevelop Programm
**'''kdevplatform''' - Die Entwicklerplatform auf der KDevelop basiert
**'''kdewebdev''' - Eine KDE Webentwicklungsapplikation
*<tt>kde-common</tt>
:Allgemeines admin/ Verzeichnis
*<tt>bugs/</tt>
:[http://bugs.kde.org/ Bugzilla] Dateien
*<tt>developer.kde.org/</tt>
:Der Inhalt von developer.kde.org
*<tt>extragear/</tt>
:KDE Programme die sich außerhalb der Haupt KDE Veröffentlichungen aufhalten
*<tt>kdereview/</tt>
:Vorübergehende Heimat für all die KDE Applikationen, von denen geglaubt wird, daß sie reif für eine Veröffentlichung sind. Von hier aus werden die Applikationen entweder nach <tt>/trunk/KDE/</tt> oder nach <tt>/trunk/extragear/</tt> verschoben, sobald die größten Probleme ausgeräumt sind.
*<tt>kdesupport/</tt>
:Unterstützende Programme und Bibliotheken für KDE
*<tt>koffice/</tt> Das KDE Office Paket, welches folgende Programme beinhaltet:
**'''karbon'''
**'''kchart'''
**'''kexi'''
**'''kformula'''
**'''kivio'''
**'''koshell'''
**'''kplato'''
**'''kpresenter'''
**'''krita'''
**'''kspread'''
**'''kugar'''
**'''kword'''
*<tt>konstruct/</tt>
:Konstruct, das KDE build Programm
*<tt>l10n-kde3/</tt>
:Übersetzungen für die "unstabilen" Module von KDE 3 (extragear, playground)
*<tt>l10n-kde4/</tt>
:Übersetzungen für KDE 4
*<tt>playground/</tt>
:Der KDE Spielplatz: Applications die gerade entwickelt werden aber noch keine Veröffentlichungsqualität erreicht haben.
*<tt>qt-copy/</tt>
:Zu Vereinfachung eine Kopie von [http://www.trolltech.com/ Trolltechs] Qt Bibliothek, auf welcher KDE basiert.
*<tt>tests/</tt>
:khtml, KOffice und ksvg Testfälle
*<tt>valgrind/</tt>
:Die Valgrind Application, welche im KDE Repository betreut wird jedoch kein Teil von KDE selber ist. Neuere Versionen von Valgrind werden in einem eigenen Repository entwickelt. Das KDE Valgrind Modul beinhaltet nur Valgrind bis zur Version 2.4.
*<tt>www/</tt>
:Webpages für die KDE Site (und verwandte Sites). Schreibzugriff auf dieses Verzeichnis ist beschränkt.

=== Das Unterverzeichnis <tt>/tags</tt> ===

Dieses Verzeichnis beinhaltet die offiziellen Veröffentlichung von den Programmen die im KDE Repository verwaltet und entwickelt werden. Jede einzelne Applikation hat hier ein Unterverzeichnis, innerhalb von diesem finden Sie die Release-Nummern.

So kann zum Beispiel der Code für KDE 3.4.0 unter <tt>/tags/KDE/3.4.0/</tt> gefunden werden.

=== Das Unterverzeichnis <tt>/branches</tt> ===

Dieses Verzeichnis beinhaltet die Zweig-versionen von Applikationen nach einer Hauptveröffentlichung.

Die meisten KDE Applikationen halten sich an die Philosophie, dass neue Features (ebenso wie neue Zeichneketten für den Benutzer) erst im nächsten Veröffentlichungszyklus — derjenige der in <tt>/trunkg/</tt> entwickelt wird — einfließen. Fehlerbereinigungen werden jedoch auf alle Applikationen angewandt, auch nach einer Veröffentlichung.

Um das zu bewerkstelligen, wird ein Zwei in dem Moment der Veröffentlichung erzeugt und zeigt damit den Status dieser Dateien zu diesem Zeitpunkt an. Fehlerbereinigungn werden dann in diese Dateien eingepflegt. Diese Zweige sind dann diejenigen die unter <tt>/branches/</tt> zu finden sind.

So kann zum Beispiel der KDE 3.4.x Zweig unter <tt>/branches/KDE/3.4/</tt> gefunden werden.

Die Unterverzeichnisse die Sie in <tt>/branches</tt> finden, sie die Unterverzeichnisse der Aplikationen wie <tt>akregator/</tt>, <tt>amarok/</tt>,
<tt>arts/</tt>, <tt>k3b/</tt>, etc. Sie finden hier auch ein <tt>KDE/</tt>
Unterverzeichnis, welches die offiziellen KDE Veröffentlichung beinhalten.

Es gibt ein spezielles Unterverzeichnis in <tt>/branches</tt> namens <tt>work/</tt>. Dieses Unterverzeichnis wird als "Arbeitszweig" berzeichnet und beinhaltet Zweige bei denen an neuen Features gearbeitet wird. Manchmal sind diese sehr experimentell. Arbeitszweige für mehrere Applikationen finden sich in <tt>/branches/work/</tt>, doch für einzelne Applikationen finden sich Arbeitszweige im jeweiligen Unterverzeichnis. Diese Entscheidung liegt bei den Entwicklern.

== Auschecken und Aktualisieren ==

=== Auschecken ===
Um entwas aus Subversion auszuchecken benutzt man das Unterkommando <tt>checkout</tt>:

'''WARNUNG:''' Wenn Sie trunk/KDE oder branches/KDE/foo auschecken werden Sie auch die komplette kde-i18n herunterladen!

Angenommen Sie wollen nur KDevelop aus dem KDE Repository auschecken, würden Sie folgende Kommandos eingeben:

CVS Kommando:
cvs -d :pserver:yourname@cvs.kde.org:/home/kde login
cvs -d :pserver:yourname@cvs.kde.org:/home/kde checkout kdevelop

Subversion Kommando:

CVS Benutzer die einen ssh Zugang besitzen, sollten das Protokoll svn+ssh,
CVS Benutzer, die einen Passwortzugang benutzen sollten das Protokoll https im folgenden benutzen.

svn checkout <protocol>://<username>@svn.kde.org/home/kde/trunk/KDE/kdevelop

=== Aktualisieren ===
Um zu aktualisieren, benutzen Sie das <tt>update</tt> Unterkommando.

Hier gibt es keinen Unterschied zu CVS: Sie wechseln in ihre ausgecheckte lokale Kopie (für diejenigen, für die das alles neu ist: die ausgecheckte Kopie sollte sich in Ihrem Heimatordner befinden) und geben ein <tt>svn update</tt> Kommando (oder kürzer <tt>svn up</tt>).

== Den Status einer Datei ermitteln ==

Um herauszufinden welche lokalen Dateien verändert wurden, haben die meisten unter CVS das Kommando cvs up aufgerufen und dann diejenigen Dateien gesucht, die mit einem '''M''' markiert waren. Das funktioniert unter svn nicht, daher müssen Sie das Kommando <tt>svn status</tt> aufrufen, um den Status der Dateien zu ermitteln.

== Ins Repository hochladen ==

Um Änderungen hochzuladen ruft man, ähnlich wie bei CVS, die Unterkommandos <tt>commit</tt> oder <tt>checkin</tt> (Kurzversion davon <tt>ci</tt>) auf.

CVS Kommando:
cvs commit
# oder
cvs ci
# oder
cvs ci filename.cpp

Subversion Kommando:
svn commit
# oder
svn ci
# oder
svn ci filename.cpp

Auf diese Weise wird <tt>svn</tt> den in <tt>$SVN_EDITOR</tt> eingetragenen Texteditor aufrufen, damit Sie das Änderungsprotokoll ausfüllen können. Wenn Sie es vorziehen, können Sie <tt>svn</tt> auch über die -m Option eine vollständige Mitteilung übergeben:

svn ci -m "Updating protocol to conform to HTTP/1.1"

== Dateien ignorieren ==

Subversion speichert die zu ignorierenden Dateien für jedes Verzeichnis. Um diese Liste für das aktuelle Verzeichnis zu bearbeiten, rufen Sie einfach
svn propedit svn:ignore .
auf. Damit wird der eingestellte Editor aufgerufen, in dem Sie die Namen der Dateien eintragen können, die ignoriert werden sollen, eine Datei pro Zeile. Wenn Sie fertig sind, einfach ein commit ausführen, damit die Dateien auf dem Server aktualisiert werden.

Eine Menge Dateien wurden bei CVS mit Hilfe der globalen Ignorierliste ignoriert, diese Liste wird von SVN nicht unterstützt. Sie können auf svn 1.3 warten oder Sie müssen die Ignorierliste in die Sammelgruppe in ihrer {{path|~/.subversion/config}} einfügen (alle in einer Zeile):

global-ignores = *.o *.lo *.la .*.rej *.rej .*~ *~ .#* #*# .DS_Store *.moc
*.moc.cc *.moc.cpp config.log config.status config.cache *.gmo .deps .libs
SunWS_cache *.lo *.la *.rpo *.la.closure *_la_closure.cpp *_la_closure.cc
*_la_closure.cxx *.all_cc.cc *.all_cpp.cpp *.all_C.C *.all_cxx.cxx
*_meta_unload.cc *_meta_unload.h *_meta_unload.cpp *_meta_unload.C
*_meta_unload.cxx index.cache.bz2 .memdump Makefile.rules.in Makefile.calls.in
Makefile.rules Makefile.calls autom4te.cache *.kidl

== Mit verschiedenen Revisionen und Branches arbeiten ==

Andes als CVS erzeugt Subversion keine Revisions-Nummer für jede veränderte Datei. Statt dessen wird das gesamte Repository als ganzes mit einer Revisions-Nummer versehen. Auf diese Art bezeichnet eine Revisions-Nummer einen bestimmten Status, den das Repository zu einem bestimmten Zeitpunkt hatte. In anderen Worten: Die Revisions-Nummer ist wie ein Zeitstempel (tatsächlich benutzt der Subversion-Server diesen Umstand, um schneller nach Daten im Repository zu suchen)

Wenn Sie also einen Check-out machen, teilt Ihnen Subversion das folgende (als Beispiel) mit:

Updated to revision 403821.

Das bedeutet, dass die letzte verfügbare Revision zu dem Zeitpunkt der Operation die Nummer 403821 ist. Wenn Sie eine Änderung vornehmen und abschicken (per commit), wird Subversion serverseitig die Revision aktualisiert und Sie davon in Kenntnis setzen. Wie in CVS werden nur die veränderten Dateien aktualisiert: Sie müssen <tt>cvs up</tt> aufrufen um den Rest der Dateien zu aktualisieren.

Möchten Sie eine bestimmte Revsision eine Dateie haben, können Sie den <tt>-r</tt> Schalter benutzen. Neben der Revisions-Nummer akzeptiert -r eine Anzahl von weiteren Möglichkeiten:

* Die Revision-Nummer: Benutzen Sie beispielsweise -r 403819 um diese Version zu erhalten
* '''BASE''': Die Revision zu der Sie aktualisiert haben
* '''COMMITTED''': Die Revision an der eine Datei vor BASE zuletzt verändert wurde.
* '''PREV''': Die Revision des vorigen commits vor COMMITTED
* '''HEAD''': Die akuellste Revision die auf dem Server verfügbar ist
* '''{ date }''': Zwischen den geschwungenen Klammern kann ein Datum angegeben werden, damit die daran nähsten Änderungen gesucht werden

Das folgende dienst der Darstellung der verschiedenen Bedeutungen der Schlüsselworte:

# Wenn mann <tt>svn up</tt> aufruft, aktualisiert man zur neusten Revision. Angenommen Subversion teilt einem mit, dass man auf Revision 403821 aktualisiert hat, dann bedeutet das, dass HEAD und BASE die Revision 403821 haben.
# Wenn man die Datei README bearbeitet und hochläd (commit), teilt einem Subversion mit, dass man die Revision 403822 hochgeladen hat. Das bedeutet HEAD, BASE und COMMITTED sind 403822.
# Jetzt wird README erneut bearbeitet und hochgeladen (via commit). Jetzt ist PREV 403822 aber HEAD, BASE und COMMITTED sind zu einem neueren Wert aktualisiert (sagen wir zum Beispiel 403823)
# Nun verändert jemand anderes das Repsitory und man selber führt ein update der Arbeitskopie durch. Subversion teilt einem mit, dass man auf 403824 aktualisiet hat, das bedeutet, dass HEAD und BASE nun auf 403824 aktualisert wurden (doch PREV und COMMITTED bleiben gleich)
# Wenn nun jemand README bearbeitet, HEAD wird verändert. Die anderen Schlüsselworte bleiben für einen selber jedoch gleich, bis man ein update durchführt. Zu diesem Zeitpunkt haben wir HEAD bei 403825 (die neuste verfügbare Revision), BASE = 403824 (die Revision, auf die zuletzt aktualisiert wurde), COMMITTED = 403823 (die Revision der letzten Änderung an der Datei als man zuletzt aktualisiert hat) und PREV = 403822 (die Revision der Änderung vor COMMITTED)

Diese Schlüsselworte sind auch nützlich um logs und diffs für Aktualisieirungen des Repositorys zu erhalten.

Wenn man sich den Unterschied zwischen der Arbeitskopie und BASE ansehen möchte, kann man

svn diff

aufrufen. Das ist eine sehr schnelle Operation, da Subversion eine lokale Kopie von BASE bereithält. Man benötigt keine Netzwerkverbindung um diese Operation durchzuführen.

Möchte man den Unterschied zwischen der lokalen Kopie und der letzten verfügbaren Version auf dem Server betrachten, ruft man

svn diff -r HEAD

auf. Möchte man sehen, was sich seit dem letzten Update am Repository geändert hat, ruft man
svn diff -r BASE:HEAD

auf. Möchte man die letzte Änderung an einer Datei vor BASE sehen, kann man
svn diff -r PREV:BASE
# oder
svn diff -r PREV:COMMITTED

aufrufen. Das gleiche gilt auch für das <tt>svn log</tt> Kommando.

== Unterverzeichnisse von anderen Orten verlinken ==

Es kann vorkommen, dass man eine Kopie eines Unterverzeichnissen von einem anderen Ort einfügen möchte. Das geschieht dann aus Bequemlichkeit und nicht um in diesem Verzeichnis Code zu schreiben. Natürlich sollte dieses Verzeichnis automatisch aktualisiert werden wann immer das Original sich ändert. Subversion kann einem dabei helfen. Man muss die Eigenschaft <tt>svn:external</tt> des Verzeichnisses bearbeiten und das Verzeichniss sollte hinzugefügt werden. Für das aktuelle Verzeichnisse benutzt man den Befehl

svn propedit svn:externals .
und gibt die Zeile
libkhalkhi svn://anonsvn.kde.org/home/kde/trunk/playground/pim/khalkhi
ein. Ein Update wird nun <tt>/trunk/playground/pim/khalkhi</tt> in das Unterverzeichnis <tt>libkhalkhi</tt> holen.

{{warning (de)|Es können jedoch keine Änderungen an der lokalen Kopie des externen Verzeichnisses hochgeladen werden, denn es ist eine nur-lesen Kopie.}}

Man kann <tt>svn://anonsvn.kde.org</tt> und kein anderes Protokoll verwnden, denn <tt>anonsvn.kde.org</tt> ist für jeden zugreifbar. Das <tt>https:</tt> oder <tt>svn+ssh:</tt> Protokoll wird nur für Benutzer funktionieren, die damit arbeiten. Es gibt noch ein paar kleine Nachteile mit <tt>anonsvn.kde.org</tt>:
Es ist nicht immer mit <tt>svn.kde.org</tt> synchronisiert, daher brauchen aktualisierungen im Originalast eine Zeit bis sie auf <tt>anonsvn.kde.org</tt> erscheinen. Außerdem blockieren eine strenge Firewalls das <tt>svn:</tt> Protokoll.

Ein spezieller Fall in KDE 3 ist das Unterverzeichnis <tt>admin</tt>, welches die KDE 3 build Werkzeuge beinhaltet. Es ist mit dem Hauptverzeichnis in allen Modulen verzeichnet und wird in <tt>/branches/KDE/3.5/kde-common</tt> bearbeitet. Für <tt>admin</tt> ist der KDE subversion Server so konfiguriert, dass es für alle einen nur-lesen Zugriff gestattet. Wenn man also
admin https://svn.kde.org/home/kde/branches/KDE/3.5/kde-common/admin
sieht, besteht kein Anlass das zu ändern.

== Mehr Informationen im KDE Wiki ==

Siehe auch [http://wiki.kde.org/tiki-index.php?page=KDE%20Subversion%20HOWTO the KDE wiki] für mehr Informationen über Subversion in KDE

Development/Architecture/KDE4/Providing Online Help (de)

2008-11-29T19:08:37Z

DrSlowDecay: Page created and translated

{{Template:I18n/Language Navigation Bar|Development/Architecture/KDE4/Providing Online Help}}

'''KDE Architecture - Providing online help'''

Ein Programm einfach und intuitiv benutzbar zu machen, umfasst eine weite Bandbreite von Einrichtungen, die man im Allgemeinen als Online Hilfe bezeichnet. Online Hilfe hat meherer teilweise widersprechende Ziele: Auf der einen Seite soll es den Benutzern Antworten auf die Frage "Wie kann ich eine bestimmte Aufgabe erledigen?" geben, auf der anderen seite sollte es dem Benutzer helfen, die Applikation zu erforschen und neue, bisher unbekannte Funktionen zu finden, die er oder sie noch nicht kannten. Es ist wichtig zu erkennen, dass dieses nur erreicht werden kann, indem man mehere Ebenen der Hilfe anbietet:

*Tooltips sind kleine Bezeichner, die erscheinen, wenn sich die Maus einige Zeit über Schnittstellenelementen befindet. Diese sind besonders für Werkzeugleisten wichtig, wo die Icons nicht immer ausreichend erklären, was ein bestimmter Knopf bewirkt.
*"What's this?" (Was ist das?) Hilfe ist üblicherweise eine längere und ausführlichere Erklärung eines Widget oder eines Menüeintrages. In Dialogen kann es auf zwei Arten aufgerufen werden: Entweder durch Drücken von Shift-F1 oder indem man auf das Fragezeichen in der Titelzeile klickt (letzters ist vom Window Manager abhängig). Der Maus Zeiger verwandelt sich in einen Pfeil mit Fragezeichen und das Hilfefenster erscheint, wenn der Benutzer das ihn interessierende Element anklickt. Die "What's this?" Hilfe für Menüeinträge wird üblicherweise über einen Knopf in der Werkzeugleiste aktiviert. Dieser zeigt einen Pfeil und ein Fragezeichen. Das Problem bei dieser Herangehensweise ist, dass der Benutzer nicht sehen kann, ob ein Widget eine Hilfe anbietet oder nicht. Wenn der Benutzer den Fragezeichenknopf aktiviert und dann keine Hilfe bekommt, wenn er ein Widget anklickt, wird er schnell frustriert werden.
 
Der Vorteil der "What's this?" Hilfe, die von Qt und KDE zur Verfügung gestellt wird, ist, dass sie [http://doc.trolltech.com/4.4/richtext.html rich text] beinhalten kann, zum Beispiel verschiedene Schriftarten, Fett- und Kursivschrift und sogar Bilder und Tabellen.
[[Image:Qt3-whatsthis.png|frame|center|QWhatsThis screenshot]]
*Zu guter Letzt sollte jedes Programm ein Handbuch haben. Ein Handbuch wird normalerweise im khelpcenter betrachtet und über das Hilfe-Menü aktiviert. Das bedeutet, dass eine komplette zusätzliche Applikation sich öffnet und den Benutzer von seiner Arbeit ablenkt. Konsequenterweise sollte daher das Befragen des Handbuches nur notwednig sein, wenn die Tooltips und "What's this?" Hilfe nicht ausreichen. Natürlich hat ein Handbuch den Vorteil, dass es nicht nur einen einzelnen, isolierter Apsekt der Benutzerschnittstelle erklärt. Statt dessen erklärt es die Aspekte einer Applikation in einem größeren Kontext. Handbücher für KDE werden mit der [http://i18n.kde.org DocBook] markup language geschrieben.

Aus der Sicht des Programmierers, bietet Qt eine einfach zu benutzende API für die Online Hilfe. Um einen Tooltip einem Widget zuzuordnen, benutze einfache die setToolTip() Methode.
<code cppqt3>
widget->setToolTip(i18n("This widget does something."))
</code>

Wenn die Menüs und Werkzeugleisten mit der [[../Action Pattern|action pattern]] erzeugt werden, wird die Zeichenkette für den Tooltip aus dem ersten Argument des [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKAction.html KAction] Konstruktors abgeleitet:

<code cppqt3>
action = new KAction(i18n("&Delete"), "editdelete",
SHIFT+Key_Delete, actionCollection(), "del")
</code>
Hier ist es auch möglich, einen Text zuzuordnen, der in der Statuszeile angezeigt wird, wenn der entsprechende Menüeintrag ausgewählt wird.

<code cppqt3>
action->setStatusText(i18n("Deletes the marked file"))
</code>

Die API für die "What's this?" Hilfe ist sehr ähnlich. In Diaglogen, benutze folgenden Code:

<code cppqt3>
widget->setWhatsThis(i18n("<qt>This demonstrates Qt's"
" rich text engine.<ul>"
"<li>Foo</li>"
"<li>Bar</li>"
"</ul></qt>"))
</code>

Für Menüeinträge benutze
<code cppqt3>
action->setWhatsThis(i18n("Deletes the marked file"))
</code>

Der Aufruf von khelpcenter wird in der
[http://api.kde.org/4.x-api/kdelibs-apidocs/kdecore/html/classKToolInvocation.html KToolInvocation] Klasse abgekapselt. Um das Handbuch deiner Applikation anzuzeigen, muß nur die statische Methode aufgerufen werden:

<code cppqt3>
KToolInvocation::invokeHelp()
</code>

Dadurch wird die erste Seite mit dem Inhaltverzeichnis dargestellt. Wenn du nur einen bestimmten Abschnitt des Handbuches anzeigen willst, kannst du ein zusätzliches Argument an invokeHeko() übergeben, welches den Anchor festlegt, zu dem der Browser springen soll.

''Ursprünglicher Autor (des englischen Artikels):'' [mailto:bernd@kdevelop.org Bernd Gehrmann]

[[Category:KDE4]]
[[Category:Architecture]]

Development/Architecture/KDE4 (de)

2008-11-29T18:36:25Z

DrSlowDecay: fixed some german links

{{Template:I18n/Language Navigation Bar|Development/Architecture/KDE4}}
== Development Framework ==

# Desktop
#* [[Development/Architecture/KDE4/Plasma (de)|Plasma - Der Desktop]]
#* [[Development/Architecture/KDE4/Sonnet|Sonnet - Technik zum Rechtschreib- und Grammatikcheck]]
#* [[Development/Architecture/KDE4/KParts (de)|KParts - Die KDE Komponentenarchitektur]]
# Hardware
#* [[Development/Architecture/KDE4/Solid|Solid - Schnittstelle zur Hardware und Netzwerken]]
#* [[Development/Architecture/KDE4/Phonon|Phonon - Multimedia framework]]
# Communication
#* [[Development/Architecture/KDE4/Decibel|Decibel - Framework für Echtzeitkommunikation]]
#* [[Development/Architecture/KDE4/Akonadi|Akonadi - Zentralisierte PIM Speicherlösung]]
# User Interface
#* [[Development/Architecture/KDE4/Providing_Online_Help (de)|Online Hilfe verfügmar machen]]
# Services
#* [[Development/Architecture/KDE4/Strigi|Strigi - Desktop Suchmaschine]]
#* [[Projects/KNS2|KNewStuff2 - Gemeinsame Daten benutzen]] (könnte hierher von den Projekten verschoben werden)

== Frameworks in anderen KDE Modulen ==

; [[Development/Architecture/KDE4/KGGZ|KGGZ]]
: Bietet Zugang zur GGZ Gaming Zone, ein freies Zentrum für Online-Spiele.

KOffice 2.0

[[Category:KDE4]][[Category:Architecture]]

Development/Architecture/KDE4/Decibel

2008-11-29T18:34:52Z

DrSlowDecay: Added language navigation

{{Template:I18n/Language Navigation Bar|Development/Architecture/KDE4/Decibel}}
'''Decibel'''

Communication, as a fundamental part of your daily work and private life, should be integrated into your desktop environment. This integration should transparently handle all the different protocols available to chat, speak or video-conference with your friends and coworkers.

Decibel wants to provide such a framework for real-time communication. It is meant to integrate traditional phone services with VoIP and instant messaging. By providing a component based service architecture, Decibel is meant to make it easy for developers to have their applications offer advanced communication and collaboration features which will allow the user to integrate this technology into their workflows.

Some features:
* Uses Tapioca -library to implement Telepathy secification
* Decibel daemon, formerly known as "Houston"
* pure Qt4 code, independent of other KDE libs.

===Further reading===
* [http://decibel.kde.org/index.php Decibel homepage]
* [http://telepathy.freedesktop.org/wiki/ Telepathy]
* [http://dot.kde.org/1170892771/ Nathan Ogden's introduction to Decibel Part I - Overview]
* [http://dot.kde.org/1171659655/ Nathan Ogden's introduction to Decibel Part II - Definitions]
* Nathan Ogden's introduction to Decibel Part III - Benefits for developers
* Nathan Ogden's introduction to Decibel Part IV - Benefits for users

[[Category:KDE4]]

Development/Architecture/KDE4/Solid

2008-11-29T18:32:29Z

DrSlowDecay: Added language navigation

{{Template:I18n/Language Navigation Bar|Development/Architecture/KDE4/Solid}}

== Seamless Hardware Interaction ==
With Solid, KDE developers are able to easily write applications with hardware interaction features. The necessary abstraction to support
cross-platform application development is provided by Solid's clear and comprehensive API.

Its aim is not the control of the devices (Solid doesn't let you syncronize your mobile phone with your local addressbook): Solid *looks for* devices and gives you access to the information it has about them. This way, you could easily look at the functions of the cpu, or at the driver that handles your camera, or the mount point of your usb pen. In sum: it gives you the possibility of "seeing without touching" your devices.

Now you would ask (at least, I asked myself): "Why should I need this library? I want to control the available hardware, not just see it!"

Well, Solid helps you a lot again: for any device interface, it gives you enough information to easily access it using other libraries or stacks. This way, if you want to manage your camera, you can use Solid to recognize it (you can use Solid::Notifier that will let you know when your camera has been plugged in), and then you can ask Solid to give you the information you need to handle it, for example with GPhoto or any other library you can think of. The same applies for any other plugged device: DVB cards (once recognized, Solid gives you the name of the associated device), audio cards (you can use ALSA, OSS or whatever you want: Solid knows the data to access it), portable media players, network cards, et cetera.
Moreover, it lets you check if you're connected to any network or not, and you can use Solid to tell the system to connect (that is, you can ask Solid: "Give me access to the network, I don't want to care about details").

Anyway, some other things needs to be said about network devices and Bluetooth. For these two classes of devices, Solid provides the "Control" namespace: that is, it lets you control them directly, without using external libraries. This means that with Solid, you can even handle your wireless or wired network interfaces, associate them to an essid, and choose ip configuration for them. You can even access your phone through Bluetooth, and so on.

The "listing" part of Solid resides in kdelibs, while the Control namespace is in kdebase.

[[Category:KDE4]]
[[Category:Architecture]]
[[Category:Solid]]

Development/Architecture/KDE4/Providing Online Help

2008-11-29T18:27:56Z

DrSlowDecay: Added language navigation

{{Template:I18n/Language Navigation Bar|Development/Architecture/KDE4/Providing Online Help}}

'''KDE Architecture - Providing online help'''

Making a program easy and intuitive to use involves a wide range of
facilities which are usually called online help. Online help has several,
partially conflicting goals: on the one, it should give the user answers
to the question "How can I do a certain task?", on the other hand it
should help the user exploring the application and finding features he
doesn't yet know about. It is important to recognize that this can only
be achieved by offering several levels of help:

*Tooltips are tiny labels that pop up over user interface elements when the mouse remains there longer. They are especially important for tool- bars, where icons are not always sufficient to explain the purpose of a button.
*"What's this?" help is usually a longer and richer explanation of a widget or a menu item. It is also more clunky to use: In dialogs, it can be invoked in two ways: either by pressing Shift-F1 or by clicking on the question mark in the title bar (where the support of the latter depends on the window manager). The mouse pointer then turns into an arrow with a question mark, and the help window appears when a user interfact element has been clicked. "What's this?" help for menu items is usually activated by a button in the toolbar which contains an arrow and a question mark. The problem with this approach is that the user can't see whether a widget provides help or not. When the user activates the question mark button and doesn't get any help window when clicking on a user interface element, he will get frustrated very quickly. The advantage of "What's this?" help windows as provided by Qt and KDE is that they can contain [http://doc.trolltech.com/4.4/richtext.html rich text], i.e. the may contain different fonts, bold and italic text and even images and tables.
[[Image:Qt3-whatsthis.png|frame|center|QWhatsThis screenshot]]
*Finally, every program should have a manual. A manual is normally viewed in khelpcenter by activating the help menu. That means, a complete additional application pops up and diverts the user from his work. Consequently, consulting the manual should only be necessary if other facilities like tooltips and what's this help are not sufficient. Of course, a manual has the advantage that it does not explain single, isolated aspects of the user interface. Instead, it can explain aspects of the application in a greater context. Manuals for KDE are written using the [http://i18n.kde.org DocBook] markup language.

From the programmer's point of view, Qt provides an easy to use API for online
help. To assign a tooltip to widget, simply use its setToolTip() method.
<code cppqt3>
widget->setToolTip(i18n("This widget does something."))
</code>

If the menu bars and tool bars are created using the [[../Action Pattern|action pattern]], the string used as tooltip is derived from the first argument
of the [http://api.kde.org/4.x-api/kdelibs-apidocs/kdeui/html/classKAction.html KAction] constructor:

<code cppqt3>
action = new KAction(i18n("&Delete"), "editdelete",
SHIFT+Key_Delete, actionCollection(), "del")
</code>

Here it is also possible to assign a text which is shown in the status bar when the respective menu item is highlighted:

<code cppqt3>
action->setStatusText(i18n("Deletes the marked file"))
</code>

The API for "What's this?' help is very similar. In dialogs, use the following
code:

<code cppqt3>
widget->setWhatsThis(i18n("<qt>This demonstrates Qt's"
" rich text engine.<ul>"
"<li>Foo</li>"
"<li>Bar</li>"
"</ul></qt>"))
</code>

For menu items, use
<code cppqt3>
action->setWhatsThis(i18n("Deletes the marked file"))
</code>

The invocation of khelpcenter is encapsulated in the
[http://api.kde.org/4.x-api/kdelibs-apidocs/kdecore/html/classKToolInvocation.html KToolInvocation]
class. In order to show the manual of your application, just use the static method:

<code cppqt3>
KToolInvocation::invokeHelp()
</code>

This displays the first page with the table of contents. When
you want to display only a certain section of the manual, you
can give an additional argument to invokeHelp() determining
the anchor which the browser jumps to.

''Initial Author:'' [mailto:bernd@kdevelop.org Bernd Gehrmann]

[[Category:KDE4]]
[[Category:Architecture]]

Development/Architecture/KDE4/KParts (de)

2008-11-29T18:24:36Z

DrSlowDecay: Page created and translated

{{Template:I18n/Language Navigation Bar|Development/Architecture/KDE4/KParts}}
'''KParts''' ist der Name des Komponenten-Frameworks für KDE: Eine einzelne Komponente wirde '''KPart''' genannt. Beispielsweise ist Konsole als ein KPart verfügbar und kann in Applikationen wie Konqueror oder Kate benutzt werden. Ein guten Beisiel, wie KParts benutzt werden können, ist Konqueror. Dieser benutzt, neben anderen, das KWord-Part um Dokumente darzustellen, den KMPlayer-Part um Multimedia abzuspielen. Ein anderes Beispiel ist Kontact, welches die einzelnen kdepim Appliaktaionen unter einem Dach vereinigt.

===Zum weiterlesen===
* [http://api.kde.org/4.0-api/kdelibs-apidocs/kparts/html/index.html KParts API Referenz]
* [http://api.kde.org/4.0-api/kdelibs-apidocs/kparts/html/classKParts_1_1Part.html KParts Klassen Referenz]
* [http://www-106.ibm.com/developerworks/library/l-kparts/ Coding with KParts] (von IBM, englisch)

[[Category:KDE4]]

Development/Architecture (de)

2008-11-29T18:17:13Z

DrSlowDecay: /* Design Dokumente */ Links to german page now

{{Template:I18n/Language Navigation Bar|Development/Architecture}}
Die folgenden Seiten beinhalten detailierte Dokumentationen über das Design und die Architektur von KDE. Sie ersetzen nicht die anderen Dokumentationen wie [http://api.kde.org API Dokumentation (englisch)], [[../Tutorials|tutorials/howtos]] und [[../Guidelines|standards]], siehe auch das [[Development (de)|Entwickler Portal]] für weitere Informationen.

Für ein besseren Verständnis könnte es helfen sich mit Trolltech's™ excellenter [http://doc.trolltech.com/3.3/index.html Qt 3.3] oder [http://doc.trolltech.com/4.3/index.html Qt 4.3] Dokumentation und deren [http://www.trolltech.com/developer/ Entwickler Seiten] zu beschäftigen.

Für mehr Informationen über eine KDE Installtion sehen Sie bitte auch die entsprechenden Kapitel in [[KDE System Administration|System Administration]].

== Design Dokumente ==
; [[Development/Architecture/KDE4 (de)|Überblick über die KDE 4 Architektur]]
: Ein Überblick über die KDE 4 Architektur einschließlich Diskussionen über allgemeine Techniken, Bibliotheksklassen und allgemeine Entwicklerfragen. Gilt für ''KDE 4.0''.

; [[Development/Architecture/KDE3|Überblick über die KDE 3 Architektur]] [http://developer.kde.org/documentation/library/kdeqt/kde3arch/ (Original)]
: Ein Überblick über die KDE 3 Architektur einschließlich Diskussionen über allgemeine Techniken, Bibliotheksklassen und allgemeine Entwicklerfragen. Gilt für ''KDE 3.0''.

; [http://developer.kde.org/documentation/library/kdeqt/kde2arch/ Überblick über die KDE 2 Architektur]
: Ein Überblick über die KDE 2 Architektur einschließlich Diskussionen über allgemeine Techniken, Bibliotheksklassen und allgemeine Entwicklerfragen. Gilt für ''KDE 2.2''.

; [[Development/Architecture/DCOP|DCOP]]
: Design Dokumente von 1999-2000.

[[Category:Architecture]]

Development/Architecture/KDE4 (de)

2008-11-29T18:14:53Z

DrSlowDecay: Created and translated

{{Template:I18n/Language Navigation Bar|Development/Architecture/KDE4}}
== Development Framework ==

# Desktop
#* [[Development/Architecture/KDE4/Plasma|Plasma - Der Desktop]]
#* [[Development/Architecture/KDE4/Sonnet|Sonnet - Technik zum Rechtschreib- und Grammatikcheck]]
#* [[Development/Architecture/KDE4/KParts|KParts - Die KDE Komponentenarchitektur]]
# Hardware
#* [[Development/Architecture/KDE4/Solid|Solid - Schnittstelle zur Hardware und Netzwerken]]
#* [[Development/Architecture/KDE4/Phonon|Phonon - Multimedia framework]]
# Communication
#* [[Development/Architecture/KDE4/Decibel|Decibel - Framework für Echtzeitkommunikation]]
#* [[Development/Architecture/KDE4/Akonadi|Akonadi - Zentralisierte PIM Speicherlösung]]
# User Interface
#* [[Development/Architecture/KDE4/Providing_Online_Help|Online Hilfe verfügmar machen]]
# Services
#* [[Development/Architecture/KDE4/Strigi|Strigi - Desktop Suchmaschine]]
#* [[Projects/KNS2|KNewStuff2 - Gemeinsame Daten benutzen]] (könnte hierher von den Projekten verschoben werden)

== Frameworks in anderen KDE Modulen ==

; [[Development/Architecture/KDE4/KGGZ|KGGZ]]
: Bietet Zugang zur GGZ Gaming Zone, ein freies Zentrum für Online-Spiele.

KOffice 2.0

[[Category:KDE4]][[Category:Architecture]]

Development (de)

2008-11-29T17:02:37Z

DrSlowDecay: Architektur links now to german page

__NOEDITSECTION__ __NOTOC__ {{Template:I18n/Language Navigation Bar|Development}}
{| style="margin: 1em 2.5% 0 2.5%; padding: 0 5px;" cellpadding="5"
|-
|colspan=2|[[Image:Discover.png|noframe]]
|-
| style="padding-left: 50px;" |[[Image:Action_launch.svg|noframe|left|40px]] ||
;[[Development/Architecture (de)|KDE Architektur]]
: Designdokumente der KDE Architektur und Technologien.
:''Mehr'': [http://api.kde.org API Dokumentation]
|-
| style="padding-left: 50px;"|[[Image:Action_configure.svg|noframe|left|40px]] ||
;[[Development/Tutorials (de)|Programmieranleitung]]
:Schritt-für-Schritt Anleitung zur KDE Entwicklung.
:''Mehr:'' [[Development/Tools|Entwicklerwerkzeuge]] | [[Development/FAQs|FAQs]]
|-
| style="padding-left: 50px;"|[[Image:Action_rebuild.svg|noframe|left|40px]] ||
;[[Development/Languages (de)|Sprachbindungen]]
:Unterstützte Programmiersprachen.
|-
| style="padding-left: 50px;" |[[Image:Action_note.svg|noframe|left|40px]] ||
;[[Development/Guidelines|Standards & Richtlinien]]
:Entwicklerrichtlinien und technische Standards die KDE verwendet.
:''Mehr:'' [[Development/Further Information|Weitere Informationen]] (Links, Bücher, Blogs, usw.)
|}

Development/Tutorials/API Documentation (de)

2008-11-29T16:53:11Z

DrSlowDecay: /* APIDOX in neuem Code schreiben */ more translated

{{Template:I18n/Language Navigation Bar|Development/Tutorials/API Documentation}}
__TOC__
{{Box|Definition|
'''API (''Application Programming Interface'') Dokumentation''' ist die Dokumentation eines ''Programmes'' und seiner Schnittstellen. Durch Dokumentation wird einem Entwickler, der mit oder an dem Programm arbeitet, erklärt, wie Dinge funktionieren und wie und welche Methoden aufzurufen sind.

API Dokumentation wird machmal auch API Referenz Handbuch (API reference manual) genannt. Es muß nicht ''nur'' ein Referenz Handbuch sein, obwohl es umfangreiches zusätzliches Material, wie Anleitungen, Zeitleisten, etc., enthalten kann. Auf dieser Seite wird alles Material welches die API eines Codes dokumentiert und erklärt "apidox" genannt.

Gute apidox benötigt etwas Mühe zum schreiben -- doch sicherlich weniger Mühe als gute ''Benutzer'' Dokumentation, da du als Entwickler für andere Entwickler schreibst und eklärst wie Code funktioniert und was er tun soll. So dein Publikum ist bereit damit zu arbeiten. Der Vorteil von apidox zeigt sich, wenn jemand anderes (oder sogar du selbst einige Monate später) den Code (wieder)verwenden oder erweitern möchte. Gute apidox bedeutet, dass jemand neues kommen kann, den Code schnell versteht und nützliche Patches erstellen kann. Gerade für Bibliotheken kann apidox es ermöglichen, diese wie eine Black Box zu benutzen (und so sollte es auch sein), da die benötigte Dokumentation vorliegt und die Dokumentation sich nicht in den tiefen des (vielleicht gar nicht vorliegenden) C codes befindet.|100%}}

== Vorwort ==

Mit APIDOX wird es anderen Entwicklern ermöglicht, auf ein Programm zuzugreifen. Sie sind nicht unbedingt notwenig doch sie helfen neuen Leuten, die an dem Programm arebeiten möchten oder den Code ohne große Änderungen wiederverwenden möchten, sicherlich eine Menge.

Ein Blick auf [http://doc.trolltech.com/latest/ die Qt Dokumentation (englisch)] ermöglicht es, einen Eindruck von guter apidox Dokumentation zu bekommen. Dort sieht man eine Stilkonsistenz, die sich durch die gesamte Dokumentation zieht. Dadurch kann man eine Menge über Qt lernen, nur indem man die Dokumentation liest. Es ist nicht notwendig, die Anleitungsprogramme auszuführen oder den Quellcode zu lesen um herauszufinden, was ein Parameter in einer bestimmten Methode einer Bibliothek macht. Es wird alles bereits erläutert.

Apidox zu schreiben besteht aus zwei Teilen. Der erste Teil ist technischer Natur: Man muß den Code verstehen, der dokumentiert werden soll, oder zumindest wissen, was er tun soll und wie er benutzt werden muss. Der andere Teil ist reine Disziplin: apidox ist am nützlichsten, wenn es sorgfältig und ausführlich benutzt wird.

Dieses Dokument versucht den apidox Prozess nicht zu ausführlich werden zu lassen, indem es einige dirkekte Tips gibt, wie man apidox schreibt. Es gibt dann doch die [[Policies/Library Documentation Policy|library apidox policies (englisch)]], die sehr viel strenger sind. Es schadet nicht, auch dort mal einen Blick reinzuwerfen.

{{note (de)|Die eigentliche Beispieldokumentation auf dieser Seite wird nicht übersetzt, da API Dokumentation in der Regel auf englisch verfasst werden, um eine internationale Mitarbeit zu ermöglichen}}

== APIDOX Basics ==

APIDOX werden durch das [http://www.doxygen.org Doxygen] Dokumentationswerkzeug verarbeitet. Dieses Werkzeug liest den Quellcode der Applikation (oder Bibliothek) und erzeugt schön formatierte Dokumentation daraus. Es gibt ein gutes [http://www.stack.nl/~dimitri/doxygen/manual.html Referenz Handbuch (auf englisch)] -- doch für die Grundlagen muß dieses nicht vollständig gelesen werden.

{{Tip|Doxygen muß für die Arbeit an apidox der Applikation nicht installiert sein. Alle paar Stunden erzeugt das [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] apidox für alle bekannten KDE Module. Logfiles und die eigentlichen Apidox werden ebenfalls bereitgestellt, um Fehlermeldungen zu entdecken und diese zu beheben. Das ist zwar nicht die schellste Methode apidox zu schreiben und zu korrigieren, doch es erledigt diese Aufgabe. Ein paar Stunden Arbeit am Tag, um an der apidox zu arbeiten, reichen aus.}}

{{Tip|Hast du Doxygen installiert und möchtest die apidox erzeugen, benutze das kdedoxygen.sh Skript wie es in [[Development/Tools/apidox|apidox (englisch)]] beschrieben ist.}}

Die Grundlagen von apidox sind einfach und machen Spaß: Man schreibt einfach Kommentare in den Code, die erklären wofür dieser ist. Diese Kommetare sind fast das gleiche wie das, was man sowieso in die header des Codes schreiben muß, so ist das ganze also nicht so schwer.

APIDOX werden in speziellen Kommentaren geschrieben. Diese Kommentare starten mit /** (Schrägstrich, Stern, Stern) -- und das ist es, was sie besonders macht. Der Rest des Kommentars ist einfacher Text, der den Teil des Programms beschreibt. Dieser Text wird vom Doxygen Prozessor interpretiert, damit dadurch passende Beschreibungen der Parameter und Rückgabewerte erfolgen kann. Doch die Dokumentation ist recht unkompliziert: Man schreibt einfach, was eine Methode tut innerhalb von /** und */, so wie folgendes Beispiel:

<code cppqt>
/** This method increases the sexyness of Kontact and should as
* such be called whenever possible (i.e. instead of having idle
* time, you might think of calling this method and helping
* Kontact gain even more popularity). You might even insert it
* into your own event loop to ensure it is called as often as
* possible. If these calls decrease the number of new features,
* it's still no problem to call it.
*/
void incSexyness(KInstance *instance);
</code>

Für eine vernünftige apidox muß jedes "Ding" des Programms dokumentiert werden. "Dinge" sind hierbei Verzeichnisse, Dateien, Namensräume, Klassen, Methoden, Aufzählungen und Variablen. Man kann eventuell Dateien und Verzeichnisse auslassen und sich nur auf die letzteren Punkte konzentrieren. Komplette apidox sehen ungefähr so aus:

<code cppqt>
/** Namespace for KDE network-related classes */
namespace KDENetwork {
/** Wrapper for a TCP/IP socket */
class Socket {
public:
/** Constructor. Calls listen() on some random high port. */
Socket();
private:
int fd;
};
}
</code>

Wie man sieht, ist jede Schachtelungsebene der eben erwähnten "Dinge" mit einem Kommentar versehen -- Der Namensraum, die Klasse und die Methode. Private "Dinge" benötigen keine apidox, protected "Dinge" jedoch schon.

Es ist wichtig, jede einzelne Schachtelungsebene zu dokumentieren, denn läßt man einen Ebene aus, ignoriert Doxygen die inneren ebenso und man findet diese nicht mehr wieder. Angenommen man würde im obigen Beispiel die Klassendokumentation weglassen, dann würde die Dokumentation für die Methode Socket() ebenfalls verschwinden. Das ist eine der typischen Fallen beim Schreiben von apidox.

Und wenn man nur eine Erklärung für jeden Teil seines Programmes schreibt, hat man schon einen großen Teil des Weges zu einer kompletten apidox hinter sich gelassen. Diese Erklärungen zu schreiben macht das Programm einfacher für andere Entwickler zu verstehen und zeigt einem oft schon sub-optimale Designs oder Namenswahlen. Auf diese Art gewinnen beide Seiten.

Man findet in der Liste von unterstützen Tags auch Beispiele für ausgefallenere apidox -- Erklärung von Parametern oder wie man die apidox mit Beispielen und Personendaten versieht. Es lohnt sich auch nachzusehen, wie man apidox aktiviert, doch es ist auch möglich die Arbeit aufzuteilen: Du schreibst die apidox selber und fragst den Originalautor (mailto:groot@kde.org), diese für dein Modul zu aktivieren. Er verspricht (zunmindest in der englischsprachigen Originalversion) das dann zu tun.

== APIDOX in neuem Code schreiben ==

Wenn mann neuen Code schreibt und dabei apidox verwenden möchte, sollte man am besten KDevelop benutzen. Vernünftig konfiguriert kann dieses automatisch ein Grundgerüst für apidox einfügen, man muß dann nur noch die eigentlichen Beschreibungen einfügen. Und man muß sich nicht mehr mit apidox kommandos rumärgern.

Wenn man sich nicht in dieser günstigen Lage befindet, sollte die folgende Checkliste einen durch die schlimmsten Untiefen beim Schreiben von apidox führen:

'''1. Schreibe die apidox direkt mit dem Code zusammen'''

Wenn man es mit etwas Disziplin schafft, direkt beim Schreiben einer Funktion foo(), wo man sich sowieso Gedanken über den gewünschten Effekt machen muss, auch gleich an die apidox zu denken, spart man sich diese Zeit sicherlich später, wenn man nicht mehr mühsam herausfinden muss, was die Funktion foo() eigentlich machen soll.

Das heißt nicht, dass man es auf diese Art und Weise machen muss, doch es bietet sich an. Durch die apidox werden auch Entscheidungen bezüglich des Designs dokumentiert. Auch wird dokumentiert, was ein bestimmter Codeabschnitt eigentlich macht, unabhängig davon, was er aktuell tut. Das macht es möglich, unabhängig zu überprüfen, ob der Code das tut, wozu er geschrieben ist. Das liegt daran, dass es bereits in der apidox dokumentiert wurde.

'''2. Dokumentierte deine Header vollständig'''

Die Header sind das, was den Benutzern als erstes vom Code ins Auge springt (in diesem Zusammenhang sind Entwickler Benutzer, die Code wiederverwenden). Aus diesem Grund sollen sie vollständig sein, d.h. jede noch so kleine Struktur sollte im Header dokumentiert werden. Im Einzelnen:

*Jede Datei sollte einen Kommentar haben, der den Nutzen dieser Datei beschreibt. Das wird von den KDE Richtlinien sowieso vorgeschrieben -- am Anfang der Datei sollte einfach vermerkt werden, wofür die Datei gut ist und in groben Zügen, was sie definiert. Das sollte in einem /** @file */ Kommentar erfolgen.
* Jeder Namensraum (namespace) sollte einen Kommentar haben. Ein bestimmter Namensraum benötigt nur einmal im Quellcodebaum einen Kommentar, doch es kann nicht schaden ihn bei jedem Auftreten erneut zu beschreiben -- nur kurz sollte es sein. Diese Kommentare sind einfache apidox Kommentare zwischen /** und */; keine besonderen Befehle wie bei Dateien das @file Befehl. 
Man sollte nur sicherstellen, dass der Kommentar direkt vor dem Namensraum steht und nichts dazwischen steht. Das folgende Beispiel zeigt, wie es aussehen soll:
<code cppqt>/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */

namespace Ungulate {
</code>
:Im nächsten Beispiel hat jemand etwas Extracode zwischen den apidox Kommentar und den Namensraum, der dokumentiert werden soll, gebracht. Das könnte Doxygen zu Fehlern bringen (in diesem Fall ist es einfach den Fehler zu finden) oder die Dokumentation des Namensraum kann sich plötzlich auf etwas ganz anderes beziehen (dann ist der Fehler schwer zu finden).
<code cppqt>
/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */
class Mammal;
namespace Ungulate {
</code>
:There is not much you can do about this except to be watching when you insert code -- don't separate apidox from the thing they are documenting.
*Every class should have a comment. Classes are the important building blocks of your application or library, so this is one place where writing lots helps. Write down why the class exists. Write down what it is supposed to do. Give an example of how to use it. Explain how not to use it, or what prerequisites it has (for instance, lots of classes need a KInstance object, but don't document that explicitly). The same caveats apply as with namespace apidox: make sure the class follows its apidox immediately.
*Every method should have a comment explaining what it does and what the parameters are for. Method parameters should be documented using @param. Don't rely on the name of the method or the parameters to be fully self-documenting. Besides, writing these things down properly will trigger Doxygen errors if you change them in an incompatible way later -- and that is going to save you lots of time in finding source and binary incompatibilities and explaining to users why their code suddenly doesn't do what they expect (assuming it compiles at all). So good method apidox is an additional insurance against making bad changes. Same caveats apply.
*Every enumeration type should have a comment explaining what the enumeration is for, even if it's just /** Various constants */.
*Every enumeration value should have a comment too, to explain what it represents. Don't rely on the name of the enumeration value being sufficiently expressive. For the purposes of readability, I suggest that you document enumeration values after the value, as opposed to the documentation format for namespaces, classes and methods where you write the documentation in front of the thing you are documenting. The format of the documentation is slightly different. Instead of writing /** Documentation */ in front, you write /**< Documentation afterards */, where the < denotes that the documentation applies to the thing just past. It looks like this:
<code cppqt>
enum State {
none, /**< No bracket seen */
bracket, /**< Found a ( for grouping */
squote, /**< Found a single quote */
dquote /**< Found double quotes */
};
</code>

'''3. Watch this space!'''

Watch the [http://www.englishbreakfastnetwork.org/ English Breakfast Network] for the [http://www.englishbreakfastnetwork.org/apidocs/ results] of your apidox work. Check the log files for errors -- Doxygen can complain quite loudly.

'''4. Write a main page for your application.'''

This is usually done in a separate file {{path|Mainpage.dox}} in the top-level of a library or application. The file's content is just a single apidox comment that starts with /** @mainpage title ; the rest of the file is just a long comment about what the library or application is for.

== APIDOX in altem Code korrigieren ==

Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)

In old apidox, you are more likely to suffer from the following symptoms:

*Missing parameter documentation (because parameters were renamed, or added, or removed, or something).
*Missing method documentation.
*Missing class documentation.
*Documentation that has wandered off on its own and is attached to the wrong thing now.

The first of these can be fixed by correcting the parameter documentation. See the examples section. The next two -- missing documentation that you can see is there in the source files but that does not show up in the generated HTML pages, is usually a matter of missing documentation on surrounding blocks. See the common pitfalls section, and make sure that the surrounding classes, namespaces and files all have documentation.

The last problem can best be fixed by moving the offending documentation back to where it belongs (really, it's not the documentation that is at fault, it's whatever has squeezed in -- the home-breaker -- between the documentation and the thing it was originally attached to). You could use some Doxygen special tags to avoid moving stuff around like that, but it does not help the understandability of the source much.

== Beispiel APIDOX ==

So what does documentation look like in the headers? How do you write a method documenation that describes the parameters as well? This section contains boilerplate for most common situations. Doxygen does not require a strict style -- it will ignore whitespace and asterisks at the beginning of a line, so you can make the documentation ASCII-pretty.

'''Documentation for a file:''' The newline after @file is significant! The text after @author is listed in a special Authors section of the apidox; you can list multiple authors.

<code cppqt>
/** @file
* This file is part of AnApplication and defines
* classes Ungulate and Moose.
*
* @author Mostly by me
*/
</code>

'''Documentation for a namespace:'''

<code cppqt>
/**
* This namespace collects functions related to
* counting and enumeration of mammals and their limbs.
*/
</code>

'''Documentation for a class:''' Some Doxygen special commands are used here to provide additional information. @author (as with files) identifies authors of the code; these are collected in a special ''Authors:'' section of the apidox. You can list more than one author. The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.

<code cppqt>
/**
* This class represents a Moose in the woodland
* simulator. A single Moose object can be created,
* but it is more useful to instantiate Moose::Factory
* by calling Moose::factory(), and then calling spawn()
* for each new Moose, since that maintains the ecological
* balance far better.
*
* @author Adriaan de Groot <degroot@kde.org>
* @since 3.5
*/
</code>

'''Method documentation:''' We can use @author and @since just like we do for classes. In addition, there are the parameters of the method that can be described. @p is used to refer to them in running text, and @param is used to construct a list of parameter descriptions that is specially formatted. Finally, @return entries describe the values that may be returned by the method.

<code cppqt>
/**
* This method names a particular Moose and as a side effect
* sets whether or not the Moose is treated as a Reindeer.
* When @p santa is @c true, the name of the moose is set to
* the next of the available Reindeer (if possible).
*
* @param name name to assign to the Moose, which is only
* relevant if the moose is not a Reindeer.
* @param santa is this Moose assigned to Santa? if so, the
* name is irrelevant.
*
* @return @c true if naming the Moose succeeded
* @return @c false if naming the Moose failed. This only
* happens if the Moose is assigned to Santa duty
* but there are already eight named Reindeer.
*/
bool name(const QString &name, bool santa = false);
</code>

Enum documentation is described in the section on writing new apidox. The same kind of documentation as for classes applies, with the addition of the documentation for each enumerated value which belongs inline.

== Beliebte Fehler ==

This section lists common pitfalls in writing apidox. Typically, they are easily
overlooked mistakes that produce weird error messages, but I will also include
some stylistic pitfalls that should be avoided.

'''Missing APIDOX''': You ''know'' you wrote dox for class Moose, but after
generation they are not visible. You ''know'' that the file-scope function int
foo() is documented, but it's not there either! What is going on?

The most common pitfall, the one that leads to "missing" apidox, is forgetting
to document surrounding structure. The "structure" in the source comes from
files, namespaces, classes and methods. In order to document a class you must
document the namespace it is in (if there is one) and the file that it is in.
In order to document a method, you must document the class it is in (and thus
the namespace and file). So the easiest rule of thumb is to
document ''everything''.
{{note (de)|This hard-and-fast rule is not quite accurate:
classes do not need the file to be documented,
so you can leave out the /** @file */ comment for
source files containing only classes (and namespaces).
Note that classes in a namespace require the namespace
to be documented, but classes in the :: namespace
don't need extra documentation.
I'm not sure about anonymous namespaces.

For file-scoped functions -- that is, functions
that are defined in a file, not in a namespace
and not in a class,
you ''must'' document the file
they are in. This applies mostly
to files which collect a bunch of non-method utility functions.}}

'''Broken parameter documentation:''' Documenting parameters to methods can be done two ways: you can document none of them, or you can document
''all'' of them for a given method. There is no middle ground (that doesn't
generate gobs of errors that you should fix).

If you document ''all'' of your parameters (which is a good thing to do,
and generates things in a nicely formatted fashion), then your method
apidox consists first of a general description of the method and then a
bunch of @param tags which describe each individual parameter. The @param
tag is followed by the name of the parameter -- watch out for spelling
and case-sensitivity! -- and then the description. The description can
span multiple lines.
<code cppqt>
/** Calculate the root-mean-square distance from the
* origin to the given integral coordinate.
*
* @param y y-coordinate, which is on an axis perpendicular to the
* x-axis, yet still in the same plane.
* @param x x-coordinate
*/
</code>

When you document all the parameters like this, Doxygen will complain if
you misspell parameter names, or forget some, or mention parameters that
are not there. This will force you to update the documentation if you
change the method signature. And that's a good thing.

Additional pitfalls are putting the type of the parameter in the list,
like @param int x, which makes "int" the name of the parameter. Another
pitfall is that @param should come after the general description.
Once the @param list starts, nothing can stop it except for other
list-style Doxygen tags like @since, @author or @return. So write @param
after the story and before, say, @return.

If you document ''none'' of the parameters, you do not use the @param tag
at all. You can talk about your parameters by writing @p before the name
of a parameter (or anything else, really, but it only makes sense in front
of a name of a parameter). Like this:
<code cppqt>
/** Calculate the root-mean-square distance from the origin to
* the given integral coordinate which is given as a pair @p x,
* @p y. If @p nonFree is true, use ESR instead of RMS in the
* computation.
*/
double distance(int x, int y, bool nonFree=false);
</code>

'''Misuse of tags in running text:''' This boils down to the warning
above about where to put @param: not every Doxygen tag can go anywhere.
Some start lists or basically end the general description part of a
description, so you need to avoid using them in running text.

'''Chosing between Doxygen errors and compiler warnings:''' If you are
going to document your parameters, you need to name them. If you are
defining a stub method, this can lead to compiler warnings.

'''Accidental tags:''' It can be easy to accidentally use Doxygen tags
in running text -- email addresses, backslash escapes, those are the
easy ones. Watch the Doxygen logs and escape that at sign with a backslash
when needed (i.e. write \@ to get an at sign). It's probably a good
idea to avoid the backslash style of apidox entirely; at the same time, if
you happen to write \moose, Doxygen will complain that that is an invalid
tag.

'''Accidental HTML:''' If you use < and > in your apidox, these may
confuse Doxygen -- especially if you write things like <service>
which look like HTML tags. This is a common way of writing some kind of
element that may be replaced in a method call or string or something, so
it crops up all the time. You know, you write some thing like this:
<code cppqt>
/** This method connects to a database. The connection string is
* composed of a username, password, host and database name as
* follows:
* <username>:<password>@<host>//<database>
*
* @return true if the connection succeeded.
*/
</code>

This bit of dox is terribly broken, because the whole sample connection
string will be interpreted as (bad) HTML and ignored. There are two
solutions:
<ol>
*Write \< instead of just < to escape the < and make Doxygen output it normally. Doxygen is smart enough to turn this into &lt; in HTML output. This has only a minimal impact on readability of the dox in the header files themselves.
*Use the HTML formatting that Doxygen makes available, and write ''foo'' instead of <foo>. This produces nicer output with italics instead of plain text, so it is easier to spot what is the replaceable part of the text. The downside is that it has a larger visible impact on the apidox in the headers.
</ol>

;Superfluous @ref
:It can be tempting -- certainly if you've written dox for other projects -- to use #method or @ref method to force a reference to another method somewhere. Relax, it's not needed and usually causes Doxygen warnings to boot. Just name the method normally, make apidox and watch the references appear naturally.

== KDE spezifische Tags ==
'''@bc''': This tag indicated binary compatibility, much like ''@since'' does. The argument after ''@bc'' is the scope of binary compatibility (for instance, KDE4). Classes that are not marked with ''@bc'' may, in some modules, be flagged as incompatible so that they can be avoided.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @bc KDE4.2 Compatibility is expected to break
* with next-generation mooses.
*/
</code>

'''@libs''': Use this tag to indicate what libraries should be linked in for the given class. Although this is usually the name of the directory the class lives in, this is not always the case.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @libs
* @a -lkdeui or use \$(LIB_KDEUI) in the KDE build framework.
*/
</code>

== Code Beispiele in APIDOX ==

Es kann nützlich sein, Beispielcode zur APIDOX einer Klasse hinzuzufügen. Sehr nützlich ist es auf jeden Fall für Leser, die sich fragen, wie man eine Klasse genau zu benutzen hat. Die meisten Klassen in {{path|kdelibs/kdecore}} haben Beispielcode.

Ein Weg, um Beispielcode zu schreiben ist es, @code und @endcode um den Block des Beispielcodes in den Doxygenkommentaren selber zu legen, wie im folgenden Beispiel:
<code cppqt>
/**
* This class represents a Moose.
* The correct way of generating Meese is to use the factory:
*
* @code
* Moose::Factory outlet = Moose::factory();
* Moose *m = outlet.spawn();
* @endcode
*/
</code>

Auf diese Art wird es in den meisten Beispielen in {{path|kdelibs}} gemacht. Das funktioniert auch ganz gut, man kann sich bei den Beispielen aufs wesentliche beschränken.

Ein wichtiges Problem dieser Herangehensweise um Beispielcode zu schreiben ist es, dass der Code niemals geprüft wird, ob er wirklich funktioniert. Die meisten Codebeispiele sind so gepackt, dass es schwer ist, diese in einen funktionsfähigen Code umzuschreiben, der wirklich kompiliert und läuft.

Um dieses Problem zu lösen, kann man ''richtigen Code'' schreiben, der wirklich kompiliert (als Teil dr Test-Suite für den Code, den man sowieso hat) und exakt beschreibt, wie eine Klasse in einem richtigen Programm benutzt werden soll. Man muß jedoch nicht den gesamten Code in die APIDOX übernehmen, sondern braucht nur die interessanten Teile zu markieren. Um das zu bewerkstelligen, wird eine Datei in das <tt>tests</tt> Unterverzeichnis eingefügt. Dann kann man das Doxygen @include-Tag benutzen, um den Code dieser Datei in die API Dokumentation zu übernehmen.

{{warning (de)|Benutze nicht @example! Es macht etwas total anderes als was du erwarten könntest (zum Beispiel fügt es keinen Beispiel-Code ein).}}

== Links ==

[http://www.stack.nl/~dimitri/doxygen/commands.html englische Liste der unterstützen Doxygen Tags]
:Hier ist eine Liste von allen verfügbaren Dokumentations-Tags von Doxygen von der offiziellen Seite. Beachte, das diese Seite ein Backslash vor einem Tag benutzt, während diese Seite immer das At-Zeichen benutzt. Beides ist erlaubt, doch in KDE sollte zu Gunsten der Konsistenz das At-Zeichen benutzt werden.

[[Category:Documentation]]

Getting Started/Sources/Subversion (de)

2008-11-29T11:38:38Z

DrSlowDecay: /* Working with multiple revisions and branches */ partly translated

{{Template:I18n/Language Navigation Bar|Getting Started/Sources/Using Subversion with KDE}}

{{TutorialBrowser (de)|

series=Anfang|

name=Subversion mit KDE benutzen|
}}

== Zusammenfassung ==

Der folgende Text ist eine schnelle kde-spezifische Einführung, wie man Subversion benutzt, um auf Dateien und Software im KDE Repository zuzugreifen. Für einen vollständigen Überblick über die Fähigkeiten von Subversion verweisen wir auf das Buch "[http://svnbook.red-bean.com/ Version Control with Subversion (englisch)]".

== Am Anfang ==

Um das KDE Subversion Repository benutzen zu können, benötigen Sie zwei Dinge:

# Ein Subversion Client Programm
# Einen Zugang zu unserem Repository

Beachte: Für einen anonymen nur-lesen Zugriff benutzen Sie das Protokoll "svn", kein "yourname@" den Server "anonsvn.kde.org" statt dem unten genannten.

'''Subversion installieren:''' Eine Anleitung zur Installtion des Client Programms wird hier nicht gegeben. Sehen Sie in den Installtionsanleitungen Ihres Systems nach, um herauszufinden, wie man Subversion installiert. Sie benötigen mindesten Version 1.1. Wenn Sie Subversion selber compilieren und Sie auf das Repository per https (und nicht über svn+ssh) zugreifen wollen, benötigen Sie SSL und ZLIB Unterstützung und müssen daher die <tt>--with-ssl --with-zlib</tt> Option übergeben.

Alternativ können Sie auch einen der zahlreich vefügbaren graphischen Clients installieren. Diese Anleitung wendet sich an personen, die nur das <tt>svn</tt> Programm benutzen und bezieht sich dabei auf Dinge die mit dem alten <tt>cvs</tt> Programm erledigt wurden.

'''Ein Benutzerkonto bekommen:''' Hatten Sie vorher ein CVS Benutzerkonto, wurde dieses zum neuen Subversion Client migriert. Wenn nicht, sehen Sie in der [[Contribute/Get_a_SVN_Account|entsprechenden Anleitung]] nach, wie man eines bekommt.

{{Note (de)|Wenn Sie ihr CVS Passwort verloren haben, gibt es einfache Wege, dieses zu ermitteln. Benutzen Sie [http://ktown.kde.org/~coolo/cvspwd.c cvspwd.c] pder [http://kdab.net/~dfaure/cvs-unscramble cvs-unscramble] (Perl).}}

== Die Struktur des KDE Repository ==

svn.kde.org/home/kde

ist die Adresse des KDE Subversion Repositorys. Das Repository wird über das HTTPS oder SVN-SSH Protokoll angesrochen, was bedeutet, dass Ihr Passwort sicher gegenüber Abhörversuche dritter ist.

Der SSL certificate md5 fingerprint für die Repositorys ist:
F6BF EDE2 D016 D1B2 4F18 742E 2C8F B7EF

Der SSL certificate sha1 fingerprint für die Repositorys ist:
e1:e6:41:96:3c:eb:ae:78:e2:73:0d:a2:32:2f:6b:21:13:bf:3d:0f

Für Personen, die svn+ssh benutzen ist hier der Fingerprint des RSA Schlüssels des Servers:
86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb

Das Repository ist in Hauptverzeichnisse organisiert:

# /branches
# /tags
# /trunk

Man kann das Repository durchforgsten über [http://websvn.kde.org/ http://websvn.kde.org/]

=== Das Unterverzeichnis /trunk ===

Das <tt>/trunk</tt> Hauptunterverzeichnis ist dasjenige, in dem die Hauptentwicklung an KDE stattfindet. Was Sie hier finden, wird als nächstes als KDE und assoziierte Programme veröffentlicht. Hier finden Sie auch das <tt>www</tt> Modul, welches die Webpages rund um KDE beinhaltet.

<tt>/trunk</tt> ist unterteilt in folgende Unterverzeichnisse:

*<tt>KDE/</tt> KDE selber, welches die nächste Veröffentlichung werden wird. Es besteht aus folgenden Modulen:
**'''kdelibs''' - KDE Hauptbibliotheken, die von allen KDE Programmen benutzt werden
**'''kdebase''' - KDE Basisprogramme, wie das KDE Control Center, Plasma (die Oberfläche) und Konqueror (der Web Browser)
**'''kdeaccessibility''' - Accessibility Dateien
**'''kdeadmin''' - KDE Administrationsprogramme
**'''kdeartwork''' - Bilder, Themen, Sounds und andere künstlerische Dateien
**'''kdebindings''' - Bindungen für andere Sprache außer C++
**'''kdeedu''' - Erzieherische und Wissenschaftliche Programme für KDE
**'''kdegames''' - KDE Spiele
**'''kdegraphics''' - KDE Graphikapplicationen
**'''kdemultimedia''' - KDE Multimediaapplicationen
**'''kdenetwork''' - KDE Netzwerkapplicationen
**'''kdepim''' - KDE Personal Information Management Applicationen
**'''kdepimlibs''' - Biblotheken, die von KDE-PIM Applicationen benötigt werden.
**'''kdesdk''' - KDE Software Development Kit Applicationen
**'''kdetoys''' - KDE Spielzeug Applicationen
**'''kdeutils''' - Allgemeine KDE Werkzeuge
**'''kdevelop''' - Das KDevelop Programm
**'''kdevplatform''' - Die Entwicklerplatform auf der KDevelop basiert
**'''kdewebdev''' - Eine KDE Webentwicklungsapplikation
*<tt>kde-common</tt>
:Allgemeines admin/ Verzeichnis
*<tt>bugs/</tt>
:[http://bugs.kde.org/ Bugzilla] Dateien
*<tt>developer.kde.org/</tt>
:Der Inhalt von developer.kde.org
*<tt>extragear/</tt>
:KDE Programme die sich außerhalb der Haupt KDE Veröffentlichungen aufhalten
*<tt>kdereview/</tt>
:Vorübergehende Heimat für all die KDE Applikationen, von denen geglaubt wird, daß sie reif für eine Veröffentlichung sind. Von hier aus werden die Applikationen entweder nach <tt>/trunk/KDE/</tt> oder nach <tt>/trunk/extragear/</tt> verschoben, sobald die größten Probleme ausgeräumt sind.
*<tt>kdesupport/</tt>
:Unterstützende Programme und Bibliotheken für KDE
*<tt>koffice/</tt> Das KDE Office Paket, welches folgende Programme beinhaltet:
**'''karbon'''
**'''kchart'''
**'''kexi'''
**'''kformula'''
**'''kivio'''
**'''koshell'''
**'''kplato'''
**'''kpresenter'''
**'''krita'''
**'''kspread'''
**'''kugar'''
**'''kword'''
*<tt>konstruct/</tt>
:Konstruct, das KDE build Programm
*<tt>l10n-kde3/</tt>
:Übersetzungen für die "unstabilen" Module von KDE 3 (extragear, playground)
*<tt>l10n-kde4/</tt>
:Übersetzungen für KDE 4
*<tt>playground/</tt>
:Der KDE Spielplatz: Applications die gerade entwickelt werden aber noch keine Veröffentlichungsqualität erreicht haben.
*<tt>qt-copy/</tt>
:Zu Vereinfachung eine Kopie von [http://www.trolltech.com/ Trolltechs] Qt Bibliothek, auf welcher KDE basiert.
*<tt>tests/</tt>
:khtml, KOffice und ksvg Testfälle
*<tt>valgrind/</tt>
:Die Valgrind Application, welche im KDE Repository betreut wird jedoch kein Teil von KDE selber ist. Neuere Versionen von Valgrind werden in einem eigenen Repository entwickelt. Das KDE Valgrind Modul beinhaltet nur Valgrind bis zur Version 2.4.
*<tt>www/</tt>
:Webpages für die KDE Site (und verwandte Sites). Schreibzugriff auf dieses Verzeichnis ist beschränkt.

=== Das Unterverzeichnis <tt>/tags</tt> ===

Dieses Verzeichnis beinhaltet die offiziellen Veröffentlichung von den Programmen die im KDE Repository verwaltet und entwickelt werden. Jede einzelne Applikation hat hier ein Unterverzeichnis, innerhalb von diesem finden Sie die Release-Nummern.

So kann zum Beispiel der Code für KDE 3.4.0 unter <tt>/tags/KDE/3.4.0/</tt> gefunden werden.

=== Das Unterverzeichnis <tt>/branches</tt> ===

Dieses Verzeichnis beinhaltet die Zweig-versionen von Applikationen nach einer Hauptveröffentlichung.

Die meisten KDE Applikationen halten sich an die Philosophie, dass neue Features (ebenso wie neue Zeichneketten für den Benutzer) erst im nächsten Veröffentlichungszyklus — derjenige der in <tt>/trunkg/</tt> entwickelt wird — einfließen. Fehlerbereinigungen werden jedoch auf alle Applikationen angewandt, auch nach einer Veröffentlichung.

Um das zu bewerkstelligen, wird ein Zwei in dem Moment der Veröffentlichung erzeugt und zeigt damit den Status dieser Dateien zu diesem Zeitpunkt an. Fehlerbereinigungn werden dann in diese Dateien eingepflegt. Diese Zweige sind dann diejenigen die unter <tt>/branches/</tt> zu finden sind.

So kann zum Beispiel der KDE 3.4.x Zweig unter <tt>/branches/KDE/3.4/</tt> gefunden werden.

Die Unterverzeichnisse die Sie in <tt>/branches</tt> finden, sie die Unterverzeichnisse der Aplikationen wie <tt>akregator/</tt>, <tt>amarok/</tt>,
<tt>arts/</tt>, <tt>k3b/</tt>, etc. Sie finden hier auch ein <tt>KDE/</tt>
Unterverzeichnis, welches die offiziellen KDE Veröffentlichung beinhalten.

Es gibt ein spezielles Unterverzeichnis in <tt>/branches</tt> namens <tt>work/</tt>. Dieses Unterverzeichnis wird als "Arbeitszweig" berzeichnet und beinhaltet Zweige bei denen an neuen Features gearbeitet wird. Manchmal sind diese sehr experimentell. Arbeitszweige für mehrere Applikationen finden sich in <tt>/branches/work/</tt>, doch für einzelne Applikationen finden sich Arbeitszweige im jeweiligen Unterverzeichnis. Diese Entscheidung liegt bei den Entwicklern.

== Auschecken und Aktualisieren ==

=== Auschecken ===
Um entwas aus Subversion auszuchecken benutzt man das Unterkommando <tt>checkout</tt>:

'''WARNUNG:''' Wenn Sie trunk/KDE oder branches/KDE/foo auschecken werden Sie auch die komplette kde-i18n herunterladen!

Angenommen Sie wollen nur KDevelop aus dem KDE Repository auschecken, würden Sie folgende Kommandos eingeben:

CVS Kommando:
cvs -d :pserver:yourname@cvs.kde.org:/home/kde login
cvs -d :pserver:yourname@cvs.kde.org:/home/kde checkout kdevelop

Subversion Kommando:

CVS Benutzer die einen ssh Zugang besitzen, sollten das Protokoll svn+ssh,
CVS Benutzer, die einen Passwortzugang benutzen sollten das Protokoll https im folgenden benutzen.

svn checkout <protocol>://<username>@svn.kde.org/home/kde/trunk/KDE/kdevelop

=== Aktualisieren ===
Um zu aktualisieren, benutzen Sie das <tt>update</tt> Unterkommando.

Hier gibt es keinen Unterschied zu CVS: Sie wechseln in ihre ausgecheckte lokale Kopie (für diejenigen, für die das alles neu ist: die ausgecheckte Kopie sollte sich in Ihrem Heimatordner befinden) und geben ein <tt>svn update</tt> Kommando (oder kürzer <tt>svn up</tt>).

== Den Status einer Datei ermitteln ==

Um herauszufinden welche lokalen Dateien verändert wurden, haben die meisten unter CVS das Kommando cvs up aufgerufen und dann diejenigen Dateien gesucht, die mit einem '''M''' markiert waren. Das funktioniert unter svn nicht, daher müssen Sie das Kommando <tt>svn status</tt> aufrufen, um den Status der Dateien zu ermitteln.

== Ins Repository hochladen ==

Um Änderungen hochzuladen ruft man, ähnlich wie bei CVS, die Unterkommandos <tt>commit</tt> oder <tt>checkin</tt> (Kurzversion davon <tt>ci</tt>) auf.

CVS Kommando:
cvs commit
# oder
cvs ci
# oder
cvs ci filename.cpp

Subversion Kommando:
svn commit
# oder
svn ci
# oder
svn ci filename.cpp

Auf diese Weise wird <tt>svn</tt> den in <tt>$SVN_EDITOR</tt> eingetragenen Texteditor aufrufen, damit Sie das Änderungsprotokoll ausfüllen können. Wenn Sie es vorziehen, können Sie <tt>svn</tt> auch über die -m Option eine vollständige Mitteilung übergeben:

svn ci -m "Updating protocol to conform to HTTP/1.1"

== Dateien ignorieren ==

Subversion speichert die zu ignorierenden Dateien für jedes Verzeichnis. Um diese Liste für das aktuelle Verzeichnis zu bearbeiten, rufen Sie einfach
svn propedit svn:ignore .
auf. Damit wird der eingestellte Editor aufgerufen, in dem Sie die Namen der Dateien eintragen können, die ignoriert werden sollen, eine Datei pro Zeile. Wenn Sie fertig sind, einfach ein commit ausführen, damit die Dateien auf dem Server aktualisiert werden.

Eine Menge Dateien wurden bei CVS mit Hilfe der globalen Ignorierliste ignoriert, diese Liste wird von SVN nicht unterstützt. Sie können auf svn 1.3 warten oder Sie müssen die Ignorierliste in die Sammelgruppe in ihrer {{path|~/.subversion/config}} einfügen (alle in einer Zeile):

global-ignores = *.o *.lo *.la .*.rej *.rej .*~ *~ .#* #*# .DS_Store *.moc
*.moc.cc *.moc.cpp config.log config.status config.cache *.gmo .deps .libs
SunWS_cache *.lo *.la *.rpo *.la.closure *_la_closure.cpp *_la_closure.cc
*_la_closure.cxx *.all_cc.cc *.all_cpp.cpp *.all_C.C *.all_cxx.cxx
*_meta_unload.cc *_meta_unload.h *_meta_unload.cpp *_meta_unload.C
*_meta_unload.cxx index.cache.bz2 .memdump Makefile.rules.in Makefile.calls.in
Makefile.rules Makefile.calls autom4te.cache *.kidl

== Mit verschiedenen Revisionen und Branches arbeiten ==

Andes als CVS erzeugt Subversion keine Revisions-Nummer für jede veränderte Datei. Statt dessen wird das gesamte Repository als ganzes mit einer Revisions-Nummer versehen. Auf diese Art bezeichnet eine Revisions-Nummer einen bestimmten Status, den das Repository zu einem bestimmten Zeitpunkt hatte. In anderen Worten: Die Revisions-Nummer ist wie ein Zeitstempel (tatsächlich benutzt der Subversion-Server diesen Umstand, um schneller nach Daten im Repository zu suchen)

Wenn Sie also einen Check-out machen, teilt Ihnen Subversion das folgende (als Beispiel) mit:

Updated to revision 403821.

Das bedeutet, dass die letzte verfügbare Revision zu dem Zeitpunkt der Operation die Nummer 403821 ist. Wenn Sie eine Änderung vornehmen und abschicken (per commit), wird Subversion serverseitig die Revision aktualisiert und Sie davon in Kenntnis setzen. Wie in CVS werden nur die veränderten Dateien aktualisiert: Sie müssen <tt>cvs up</tt> aufrufen um den Rest der Dateien zu aktualisieren.

Möchten Sie eine bestimmte Revsision eine Dateie haben, können Sie den <tt>-r</tt> Schalter benutzen. Neben der Revisions-Nummer akzeptiert -r eine Anzahl von weiteren Möglichkeiten:

* Die Revision-Nummer: Benutzen Sie beispielsweise -r 403819 um diese Version zu erhalten
* '''BASE''': Die Revision zu der Sie aktualisiert haben
* '''COMMITTED''': Die Revision an der eine Datei vor BASE zuletzt verändert wurde.
* '''PREV''': Die Revision des vorigen commits vor COMMITTED
* '''HEAD''': Die akuellste Revision die auf dem Server verfügbar ist
* '''{ date }''': Zwischen den geschwungenen Klammern kann ein Datum angegeben werden, damit die daran nähsten Änderungen gesucht werden

The following illustrates the evolution of the keywords:

# You run <tt>svn up</tt> to update to the latest available revision. Suppose Subversion tells you it updated to revision 403821. This means that HEAD and BASE are 403821.
# You modify file README and commit it. Suppose Subversion tells you it committed revision 403822. This means HEAD, BASE and COMMITTED are 403822.
# You modify the file again and commit it. Now PREV is 403822, but HEAD, BASE and COMMITTED are updated to a new value (suppose it's 403823).
# Now someone else modifies the repository, and you update your working copy. If Subversion tells you it updated to 403824, this means now HEAD and BASE are moved to 403824 (but PREV and COMMITTED stay the same)
# If someone modifies the README file now, HEAD is moved. The other keywords stay the same for you, until you update. At this time, we will have HEAD = 403825 (the latest available revision), BASE = 403824 (the revision you last updated to), COMMITTED = 403823 (the revision of the latest change to the file when you last updated) and PREV = 403822 (the revision of the change before COMMITTED)

Those keywords are useful to retrieve logs and diffs for commits to the
repository.

If you want to see the difference between your working copy and BASE, you
can run:

svn diff

This is a very fast operation, since Subversion keeps a local copy of BASE.
It doesn't need a network connection to accomplish this operation.

If you want to see the difference between your local copy and the latest
available on the server, you will run:

svn diff -r HEAD

If you want to see what has changed in the repository since you've last updated, you can use:
svn diff -r BASE:HEAD

If you want to see the last change to a file before BASE, you can use:
svn diff -r PREV:BASE
# or
svn diff -r PREV:COMMITTED

That is also valid for the <tt>svn log</tt> command.

== Unterverzeichnisse von anderen Orten verlinken ==

It can happen you would like to include a copy of a subdirectory from another place, but just for convenience, not for developing the code in there. Of course it should be updated automatically whenever the original changes. Subversion can help you. You need to edit the property <tt>svn:external</tt> of the directory the subdirectory should be added to. So for the current directory you use
svn propedit svn:externals .
and then enter lines of the form
libkhalkhi svn://anonsvn.kde.org/home/kde/trunk/playground/pim/khalkhi
Updating will now fetch <tt>/trunk/playground/pim/khalkhi</tt> into the subdirectoy <tt>libkhalkhi</tt>.

{{warning (de)|Beware that you cannot commit changes you did to the local copy of the external subdirectory, it is just a readonly copy.}}

You use <tt>svn://anonsvn.kde.org</tt> and not another protocol, because <tt>anonsvn.kde.org</tt> is accessible to everyone. Using <tt>https:</tt> or <tt>svn+ssh:</tt> would only work for users of that protocol. There are still some small disadvantage with <tt>anonsvn.kde.org</tt>: It is not always in synchronization with <tt>svn.kde.org</tt>, so updates in the original branch may take a while to appear on <tt>anonsvn.kde.org</tt>. And some strict firewalls are blocking the <tt>svn:</tt> protocol.

A special case in KDE 3 is the subdirectory <tt>admin</tt>, containing the KDE 3 build utilities. It is linked in to the top directory in all modules, and maintained in <tt>/branches/KDE/3.5/kde-common</tt>. For <tt>admin</tt> the KDE subversion server is configured to allow readonly access for everyone, so if you see
admin https://svn.kde.org/home/kde/branches/KDE/3.5/kde-common/admin
there is no need to change this.

== Mehr Informationen im KDE Wiki ==

Siehe auch [http://wiki.kde.org/tiki-index.php?page=KDE%20Subversion%20HOWTO the KDE wiki] für mehr Informationen über Subversion in KDE

Getting Started/Sources/Subversion (de)

2008-11-29T11:21:55Z

DrSlowDecay: /* Dateien ignorieren */ More translation

{{Template:I18n/Language Navigation Bar|Getting Started/Sources/Using Subversion with KDE}}

{{TutorialBrowser (de)|

series=Anfang|

name=Subversion mit KDE benutzen|
}}

== Zusammenfassung ==

Der folgende Text ist eine schnelle kde-spezifische Einführung, wie man Subversion benutzt, um auf Dateien und Software im KDE Repository zuzugreifen. Für einen vollständigen Überblick über die Fähigkeiten von Subversion verweisen wir auf das Buch "[http://svnbook.red-bean.com/ Version Control with Subversion (englisch)]".

== Am Anfang ==

Um das KDE Subversion Repository benutzen zu können, benötigen Sie zwei Dinge:

# Ein Subversion Client Programm
# Einen Zugang zu unserem Repository

Beachte: Für einen anonymen nur-lesen Zugriff benutzen Sie das Protokoll "svn", kein "yourname@" den Server "anonsvn.kde.org" statt dem unten genannten.

'''Subversion installieren:''' Eine Anleitung zur Installtion des Client Programms wird hier nicht gegeben. Sehen Sie in den Installtionsanleitungen Ihres Systems nach, um herauszufinden, wie man Subversion installiert. Sie benötigen mindesten Version 1.1. Wenn Sie Subversion selber compilieren und Sie auf das Repository per https (und nicht über svn+ssh) zugreifen wollen, benötigen Sie SSL und ZLIB Unterstützung und müssen daher die <tt>--with-ssl --with-zlib</tt> Option übergeben.

Alternativ können Sie auch einen der zahlreich vefügbaren graphischen Clients installieren. Diese Anleitung wendet sich an personen, die nur das <tt>svn</tt> Programm benutzen und bezieht sich dabei auf Dinge die mit dem alten <tt>cvs</tt> Programm erledigt wurden.

'''Ein Benutzerkonto bekommen:''' Hatten Sie vorher ein CVS Benutzerkonto, wurde dieses zum neuen Subversion Client migriert. Wenn nicht, sehen Sie in der [[Contribute/Get_a_SVN_Account|entsprechenden Anleitung]] nach, wie man eines bekommt.

{{Note (de)|Wenn Sie ihr CVS Passwort verloren haben, gibt es einfache Wege, dieses zu ermitteln. Benutzen Sie [http://ktown.kde.org/~coolo/cvspwd.c cvspwd.c] pder [http://kdab.net/~dfaure/cvs-unscramble cvs-unscramble] (Perl).}}

== Die Struktur des KDE Repository ==

svn.kde.org/home/kde

ist die Adresse des KDE Subversion Repositorys. Das Repository wird über das HTTPS oder SVN-SSH Protokoll angesrochen, was bedeutet, dass Ihr Passwort sicher gegenüber Abhörversuche dritter ist.

Der SSL certificate md5 fingerprint für die Repositorys ist:
F6BF EDE2 D016 D1B2 4F18 742E 2C8F B7EF

Der SSL certificate sha1 fingerprint für die Repositorys ist:
e1:e6:41:96:3c:eb:ae:78:e2:73:0d:a2:32:2f:6b:21:13:bf:3d:0f

Für Personen, die svn+ssh benutzen ist hier der Fingerprint des RSA Schlüssels des Servers:
86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb

Das Repository ist in Hauptverzeichnisse organisiert:

# /branches
# /tags
# /trunk

Man kann das Repository durchforgsten über [http://websvn.kde.org/ http://websvn.kde.org/]

=== Das Unterverzeichnis /trunk ===

Das <tt>/trunk</tt> Hauptunterverzeichnis ist dasjenige, in dem die Hauptentwicklung an KDE stattfindet. Was Sie hier finden, wird als nächstes als KDE und assoziierte Programme veröffentlicht. Hier finden Sie auch das <tt>www</tt> Modul, welches die Webpages rund um KDE beinhaltet.

<tt>/trunk</tt> ist unterteilt in folgende Unterverzeichnisse:

*<tt>KDE/</tt> KDE selber, welches die nächste Veröffentlichung werden wird. Es besteht aus folgenden Modulen:
**'''kdelibs''' - KDE Hauptbibliotheken, die von allen KDE Programmen benutzt werden
**'''kdebase''' - KDE Basisprogramme, wie das KDE Control Center, Plasma (die Oberfläche) und Konqueror (der Web Browser)
**'''kdeaccessibility''' - Accessibility Dateien
**'''kdeadmin''' - KDE Administrationsprogramme
**'''kdeartwork''' - Bilder, Themen, Sounds und andere künstlerische Dateien
**'''kdebindings''' - Bindungen für andere Sprache außer C++
**'''kdeedu''' - Erzieherische und Wissenschaftliche Programme für KDE
**'''kdegames''' - KDE Spiele
**'''kdegraphics''' - KDE Graphikapplicationen
**'''kdemultimedia''' - KDE Multimediaapplicationen
**'''kdenetwork''' - KDE Netzwerkapplicationen
**'''kdepim''' - KDE Personal Information Management Applicationen
**'''kdepimlibs''' - Biblotheken, die von KDE-PIM Applicationen benötigt werden.
**'''kdesdk''' - KDE Software Development Kit Applicationen
**'''kdetoys''' - KDE Spielzeug Applicationen
**'''kdeutils''' - Allgemeine KDE Werkzeuge
**'''kdevelop''' - Das KDevelop Programm
**'''kdevplatform''' - Die Entwicklerplatform auf der KDevelop basiert
**'''kdewebdev''' - Eine KDE Webentwicklungsapplikation
*<tt>kde-common</tt>
:Allgemeines admin/ Verzeichnis
*<tt>bugs/</tt>
:[http://bugs.kde.org/ Bugzilla] Dateien
*<tt>developer.kde.org/</tt>
:Der Inhalt von developer.kde.org
*<tt>extragear/</tt>
:KDE Programme die sich außerhalb der Haupt KDE Veröffentlichungen aufhalten
*<tt>kdereview/</tt>
:Vorübergehende Heimat für all die KDE Applikationen, von denen geglaubt wird, daß sie reif für eine Veröffentlichung sind. Von hier aus werden die Applikationen entweder nach <tt>/trunk/KDE/</tt> oder nach <tt>/trunk/extragear/</tt> verschoben, sobald die größten Probleme ausgeräumt sind.
*<tt>kdesupport/</tt>
:Unterstützende Programme und Bibliotheken für KDE
*<tt>koffice/</tt> Das KDE Office Paket, welches folgende Programme beinhaltet:
**'''karbon'''
**'''kchart'''
**'''kexi'''
**'''kformula'''
**'''kivio'''
**'''koshell'''
**'''kplato'''
**'''kpresenter'''
**'''krita'''
**'''kspread'''
**'''kugar'''
**'''kword'''
*<tt>konstruct/</tt>
:Konstruct, das KDE build Programm
*<tt>l10n-kde3/</tt>
:Übersetzungen für die "unstabilen" Module von KDE 3 (extragear, playground)
*<tt>l10n-kde4/</tt>
:Übersetzungen für KDE 4
*<tt>playground/</tt>
:Der KDE Spielplatz: Applications die gerade entwickelt werden aber noch keine Veröffentlichungsqualität erreicht haben.
*<tt>qt-copy/</tt>
:Zu Vereinfachung eine Kopie von [http://www.trolltech.com/ Trolltechs] Qt Bibliothek, auf welcher KDE basiert.
*<tt>tests/</tt>
:khtml, KOffice und ksvg Testfälle
*<tt>valgrind/</tt>
:Die Valgrind Application, welche im KDE Repository betreut wird jedoch kein Teil von KDE selber ist. Neuere Versionen von Valgrind werden in einem eigenen Repository entwickelt. Das KDE Valgrind Modul beinhaltet nur Valgrind bis zur Version 2.4.
*<tt>www/</tt>
:Webpages für die KDE Site (und verwandte Sites). Schreibzugriff auf dieses Verzeichnis ist beschränkt.

=== Das Unterverzeichnis <tt>/tags</tt> ===

Dieses Verzeichnis beinhaltet die offiziellen Veröffentlichung von den Programmen die im KDE Repository verwaltet und entwickelt werden. Jede einzelne Applikation hat hier ein Unterverzeichnis, innerhalb von diesem finden Sie die Release-Nummern.

So kann zum Beispiel der Code für KDE 3.4.0 unter <tt>/tags/KDE/3.4.0/</tt> gefunden werden.

=== Das Unterverzeichnis <tt>/branches</tt> ===

Dieses Verzeichnis beinhaltet die Zweig-versionen von Applikationen nach einer Hauptveröffentlichung.

Die meisten KDE Applikationen halten sich an die Philosophie, dass neue Features (ebenso wie neue Zeichneketten für den Benutzer) erst im nächsten Veröffentlichungszyklus — derjenige der in <tt>/trunkg/</tt> entwickelt wird — einfließen. Fehlerbereinigungen werden jedoch auf alle Applikationen angewandt, auch nach einer Veröffentlichung.

Um das zu bewerkstelligen, wird ein Zwei in dem Moment der Veröffentlichung erzeugt und zeigt damit den Status dieser Dateien zu diesem Zeitpunkt an. Fehlerbereinigungn werden dann in diese Dateien eingepflegt. Diese Zweige sind dann diejenigen die unter <tt>/branches/</tt> zu finden sind.

So kann zum Beispiel der KDE 3.4.x Zweig unter <tt>/branches/KDE/3.4/</tt> gefunden werden.

Die Unterverzeichnisse die Sie in <tt>/branches</tt> finden, sie die Unterverzeichnisse der Aplikationen wie <tt>akregator/</tt>, <tt>amarok/</tt>,
<tt>arts/</tt>, <tt>k3b/</tt>, etc. Sie finden hier auch ein <tt>KDE/</tt>
Unterverzeichnis, welches die offiziellen KDE Veröffentlichung beinhalten.

Es gibt ein spezielles Unterverzeichnis in <tt>/branches</tt> namens <tt>work/</tt>. Dieses Unterverzeichnis wird als "Arbeitszweig" berzeichnet und beinhaltet Zweige bei denen an neuen Features gearbeitet wird. Manchmal sind diese sehr experimentell. Arbeitszweige für mehrere Applikationen finden sich in <tt>/branches/work/</tt>, doch für einzelne Applikationen finden sich Arbeitszweige im jeweiligen Unterverzeichnis. Diese Entscheidung liegt bei den Entwicklern.

== Auschecken und Aktualisieren ==

=== Auschecken ===
Um entwas aus Subversion auszuchecken benutzt man das Unterkommando <tt>checkout</tt>:

'''WARNUNG:''' Wenn Sie trunk/KDE oder branches/KDE/foo auschecken werden Sie auch die komplette kde-i18n herunterladen!

Angenommen Sie wollen nur KDevelop aus dem KDE Repository auschecken, würden Sie folgende Kommandos eingeben:

CVS Kommando:
cvs -d :pserver:yourname@cvs.kde.org:/home/kde login
cvs -d :pserver:yourname@cvs.kde.org:/home/kde checkout kdevelop

Subversion Kommando:

CVS Benutzer die einen ssh Zugang besitzen, sollten das Protokoll svn+ssh,
CVS Benutzer, die einen Passwortzugang benutzen sollten das Protokoll https im folgenden benutzen.

svn checkout <protocol>://<username>@svn.kde.org/home/kde/trunk/KDE/kdevelop

=== Aktualisieren ===
Um zu aktualisieren, benutzen Sie das <tt>update</tt> Unterkommando.

Hier gibt es keinen Unterschied zu CVS: Sie wechseln in ihre ausgecheckte lokale Kopie (für diejenigen, für die das alles neu ist: die ausgecheckte Kopie sollte sich in Ihrem Heimatordner befinden) und geben ein <tt>svn update</tt> Kommando (oder kürzer <tt>svn up</tt>).

== Den Status einer Datei ermitteln ==

Um herauszufinden welche lokalen Dateien verändert wurden, haben die meisten unter CVS das Kommando cvs up aufgerufen und dann diejenigen Dateien gesucht, die mit einem '''M''' markiert waren. Das funktioniert unter svn nicht, daher müssen Sie das Kommando <tt>svn status</tt> aufrufen, um den Status der Dateien zu ermitteln.

== Ins Repository hochladen ==

Um Änderungen hochzuladen ruft man, ähnlich wie bei CVS, die Unterkommandos <tt>commit</tt> oder <tt>checkin</tt> (Kurzversion davon <tt>ci</tt>) auf.

CVS Kommando:
cvs commit
# oder
cvs ci
# oder
cvs ci filename.cpp

Subversion Kommando:
svn commit
# oder
svn ci
# oder
svn ci filename.cpp

Auf diese Weise wird <tt>svn</tt> den in <tt>$SVN_EDITOR</tt> eingetragenen Texteditor aufrufen, damit Sie das Änderungsprotokoll ausfüllen können. Wenn Sie es vorziehen, können Sie <tt>svn</tt> auch über die -m Option eine vollständige Mitteilung übergeben:

svn ci -m "Updating protocol to conform to HTTP/1.1"

== Dateien ignorieren ==

Subversion speichert die zu ignorierenden Dateien für jedes Verzeichnis. Um diese Liste für das aktuelle Verzeichnis zu bearbeiten, rufen Sie einfach
svn propedit svn:ignore .
auf. Damit wird der eingestellte Editor aufgerufen, in dem Sie die Namen der Dateien eintragen können, die ignoriert werden sollen, eine Datei pro Zeile. Wenn Sie fertig sind, einfach ein commit ausführen, damit die Dateien auf dem Server aktualisiert werden.

Eine Menge Dateien wurden bei CVS mit Hilfe der globalen Ignorierliste ignoriert, diese Liste wird von SVN nicht unterstützt. Sie können auf svn 1.3 warten oder Sie müssen die Ignorierliste in die Sammelgruppe in ihrer {{path|~/.subversion/config}} einfügen (alle in einer Zeile):

global-ignores = *.o *.lo *.la .*.rej *.rej .*~ *~ .#* #*# .DS_Store *.moc
*.moc.cc *.moc.cpp config.log config.status config.cache *.gmo .deps .libs
SunWS_cache *.lo *.la *.rpo *.la.closure *_la_closure.cpp *_la_closure.cc
*_la_closure.cxx *.all_cc.cc *.all_cpp.cpp *.all_C.C *.all_cxx.cxx
*_meta_unload.cc *_meta_unload.h *_meta_unload.cpp *_meta_unload.C
*_meta_unload.cxx index.cache.bz2 .memdump Makefile.rules.in Makefile.calls.in
Makefile.rules Makefile.calls autom4te.cache *.kidl

== Working with multiple revisions and branches ==

Unlike CVS, Subversion doesn't generate a revision number for each file
modified. Instead, the full repository is versioned, as a whole. This way, a
given revision number represents the state the repository was on a given date.
In other words, a revision number is like a timestamp (in fact, the Subversion
server uses this fact to search for dates in the repository faster).

So, for instance, when you check out the KDE repository, Subversion will
tell you the following:

Updated to revision 403821.

This means that the latest revision available at the time of the operation
was 403821. If you make a modification and commit, Subversion will update the
server-side revision and will inform you of it. Like CVS, only the committed
files will be updated: you will need run <tt>cvs up</tt> to update the rest of the
files.

If you want to retrieve a specific revision of a file, you can use the <tt>-r</tt>
switch. Besides the revision number itself, -r accepts a number of other
possibilities:

* The revision number: for example, use -r 403819 to retrieve that version
* '''BASE''': the revision you updated to
* '''COMMITTED''': the revision a file was last modified, before BASE
* '''PREV''': the revision of the previous commit to the file before COMMITTED
* '''HEAD''': the most recent revision available in the server
* '''{ date }''': between curly brackets, you can specify a date for searching the closest revisions

The following illustrates the evolution of the keywords:

# You run <tt>svn up</tt> to update to the latest available revision. Suppose Subversion tells you it updated to revision 403821. This means that HEAD and BASE are 403821.
# You modify file README and commit it. Suppose Subversion tells you it committed revision 403822. This means HEAD, BASE and COMMITTED are 403822.
# You modify the file again and commit it. Now PREV is 403822, but HEAD, BASE and COMMITTED are updated to a new value (suppose it's 403823).
# Now someone else modifies the repository, and you update your working copy. If Subversion tells you it updated to 403824, this means now HEAD and BASE are moved to 403824 (but PREV and COMMITTED stay the same)
# If someone modifies the README file now, HEAD is moved. The other keywords stay the same for you, until you update. At this time, we will have HEAD = 403825 (the latest available revision), BASE = 403824 (the revision you last updated to), COMMITTED = 403823 (the revision of the latest change to the file when you last updated) and PREV = 403822 (the revision of the change before COMMITTED)

Those keywords are useful to retrieve logs and diffs for commits to the
repository.

If you want to see the difference between your working copy and BASE, you
can run:

svn diff

This is a very fast operation, since Subversion keeps a local copy of BASE.
It doesn't need a network connection to accomplish this operation.

If you want to see the difference between your local copy and the latest
available on the server, you will run:

svn diff -r HEAD

If you want to see what has changed in the repository since you've last updated, you can use:
svn diff -r BASE:HEAD

If you want to see the last change to a file before BASE, you can use:
svn diff -r PREV:BASE
# or
svn diff -r PREV:COMMITTED

That is also valid for the <tt>svn log</tt> command.

== Unterverzeichnisse von anderen Orten verlinken ==

It can happen you would like to include a copy of a subdirectory from another place, but just for convenience, not for developing the code in there. Of course it should be updated automatically whenever the original changes. Subversion can help you. You need to edit the property <tt>svn:external</tt> of the directory the subdirectory should be added to. So for the current directory you use
svn propedit svn:externals .
and then enter lines of the form
libkhalkhi svn://anonsvn.kde.org/home/kde/trunk/playground/pim/khalkhi
Updating will now fetch <tt>/trunk/playground/pim/khalkhi</tt> into the subdirectoy <tt>libkhalkhi</tt>.

{{warning (de)|Beware that you cannot commit changes you did to the local copy of the external subdirectory, it is just a readonly copy.}}

You use <tt>svn://anonsvn.kde.org</tt> and not another protocol, because <tt>anonsvn.kde.org</tt> is accessible to everyone. Using <tt>https:</tt> or <tt>svn+ssh:</tt> would only work for users of that protocol. There are still some small disadvantage with <tt>anonsvn.kde.org</tt>: It is not always in synchronization with <tt>svn.kde.org</tt>, so updates in the original branch may take a while to appear on <tt>anonsvn.kde.org</tt>. And some strict firewalls are blocking the <tt>svn:</tt> protocol.

A special case in KDE 3 is the subdirectory <tt>admin</tt>, containing the KDE 3 build utilities. It is linked in to the top directory in all modules, and maintained in <tt>/branches/KDE/3.5/kde-common</tt>. For <tt>admin</tt> the KDE subversion server is configured to allow readonly access for everyone, so if you see
admin https://svn.kde.org/home/kde/branches/KDE/3.5/kde-common/admin
there is no need to change this.

== Mehr Informationen im KDE Wiki ==

Siehe auch [http://wiki.kde.org/tiki-index.php?page=KDE%20Subversion%20HOWTO the KDE wiki] für mehr Informationen über Subversion in KDE

Development/Tutorials/API Documentation (de)

2008-11-20T15:40:58Z

DrSlowDecay: /* Code Beispiele in APIDOX */ More translation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/API Documentation}}
__TOC__
{{Box|Definition|
'''API (''Application Programming Interface'') Dokumentation''' ist die Dokumentation eines ''Programmes'' und seiner Schnittstellen. Durch Dokumentation wird einem Entwickler, der mit oder an dem Programm arbeitet, erklärt, wie Dinge funktionieren und wie und welche Methoden aufzurufen sind.

API Dokumentation wird machmal auch API Referenz Handbuch (API reference manual) genannt. Es muß nicht ''nur'' ein Referenz Handbuch sein, obwohl es umfangreiches zusätzliches Material, wie Anleitungen, Zeitleisten, etc., enthalten kann. Auf dieser Seite wird alles Material welches die API eines Codes dokumentiert und erklärt "apidox" genannt.

Gute apidox benötigt etwas Mühe zum schreiben -- doch sicherlich weniger Mühe als gute ''Benutzer'' Dokumentation, da du als Entwickler für andere Entwickler schreibst und eklärst wie Code funktioniert und was er tun soll. So dein Publikum ist bereit damit zu arbeiten. Der Vorteil von apidox zeigt sich, wenn jemand anderes (oder sogar du selbst einige Monate später) den Code (wieder)verwenden oder erweitern möchte. Gute apidox bedeutet, dass jemand neues kommen kann, den Code schnell versteht und nützliche Patches erstellen kann. Gerade für Bibliotheken kann apidox es ermöglichen, diese wie eine Black Box zu benutzen (und so sollte es auch sein), da die benötigte Dokumentation vorliegt und die Dokumentation sich nicht in den tiefen des (vielleicht gar nicht vorliegenden) C codes befindet.|100%}}

== Vorwort ==

Mit APIDOX wird es anderen Entwicklern ermöglicht, auf ein Programm zuzugreifen. Sie sind nicht unbedingt notwenig doch sie helfen neuen Leuten, die an dem Programm arebeiten möchten oder den Code ohne große Änderungen wiederverwenden möchten, sicherlich eine Menge.

Ein Blick auf [http://doc.trolltech.com/latest/ die Qt Dokumentation (englisch)] ermöglicht es, einen Eindruck von guter apidox Dokumentation zu bekommen. Dort sieht man eine Stilkonsistenz, die sich durch die gesamte Dokumentation zieht. Dadurch kann man eine Menge über Qt lernen, nur indem man die Dokumentation liest. Es ist nicht notwendig, die Anleitungsprogramme auszuführen oder den Quellcode zu lesen um herauszufinden, was ein Parameter in einer bestimmten Methode einer Bibliothek macht. Es wird alles bereits erläutert.

Apidox zu schreiben besteht aus zwei Teilen. Der erste Teil ist technischer Natur: Man muß den Code verstehen, der dokumentiert werden soll, oder zumindest wissen, was er tun soll und wie er benutzt werden muss. Der andere Teil ist reine Disziplin: apidox ist am nützlichsten, wenn es sorgfältig und ausführlich benutzt wird.

Dieses Dokument versucht den apidox Prozess nicht zu ausführlich werden zu lassen, indem es einige dirkekte Tips gibt, wie man apidox schreibt. Es gibt dann doch die [[Policies/Library Documentation Policy|library apidox policies (englisch)]], die sehr viel strenger sind. Es schadet nicht, auch dort mal einen Blick reinzuwerfen.

{{note (de)|Die eigentliche Beispieldokumentation auf dieser Seite wird nicht übersetzt, da API Dokumentation in der Regel auf englisch verfasst werden, um eine internationale Mitarbeit zu ermöglichen}}

== APIDOX Basics ==

APIDOX werden durch das [http://www.doxygen.org Doxygen] Dokumentationswerkzeug verarbeitet. Dieses Werkzeug liest den Quellcode der Applikation (oder Bibliothek) und erzeugt schön formatierte Dokumentation daraus. Es gibt ein gutes [http://www.stack.nl/~dimitri/doxygen/manual.html Referenz Handbuch (auf englisch)] -- doch für die Grundlagen muß dieses nicht vollständig gelesen werden.

{{Tip|Doxygen muß für die Arbeit an apidox der Applikation nicht installiert sein. Alle paar Stunden erzeugt das [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] apidox für alle bekannten KDE Module. Logfiles und die eigentlichen Apidox werden ebenfalls bereitgestellt, um Fehlermeldungen zu entdecken und diese zu beheben. Das ist zwar nicht die schellste Methode apidox zu schreiben und zu korrigieren, doch es erledigt diese Aufgabe. Ein paar Stunden Arbeit am Tag, um an der apidox zu arbeiten, reichen aus.}}

{{Tip|Hast du Doxygen installiert und möchtest die apidox erzeugen, benutze das kdedoxygen.sh Skript wie es in [[Development/Tools/apidox|apidox (englisch)]] beschrieben ist.}}

Die Grundlagen von apidox sind einfach und machen Spaß: Man schreibt einfach Kommentare in den Code, die erklären wofür dieser ist. Diese Kommetare sind fast das gleiche wie das, was man sowieso in die header des Codes schreiben muß, so ist das ganze also nicht so schwer.

APIDOX werden in speziellen Kommentaren geschrieben. Diese Kommentare starten mit /** (Schrägstrich, Stern, Stern) -- und das ist es, was sie besonders macht. Der Rest des Kommentars ist einfacher Text, der den Teil des Programms beschreibt. Dieser Text wird vom Doxygen Prozessor interpretiert, damit dadurch passende Beschreibungen der Parameter und Rückgabewerte erfolgen kann. Doch die Dokumentation ist recht unkompliziert: Man schreibt einfach, was eine Methode tut innerhalb von /** und */, so wie folgendes Beispiel:

<code cppqt>
/** This method increases the sexyness of Kontact and should as
* such be called whenever possible (i.e. instead of having idle
* time, you might think of calling this method and helping
* Kontact gain even more popularity). You might even insert it
* into your own event loop to ensure it is called as often as
* possible. If these calls decrease the number of new features,
* it's still no problem to call it.
*/
void incSexyness(KInstance *instance);
</code>

Für eine vernünftige apidox muß jedes "Ding" des Programms dokumentiert werden. "Dinge" sind hierbei Verzeichnisse, Dateien, Namensräume, Klassen, Methoden, Aufzählungen und Variablen. Man kann eventuell Dateien und Verzeichnisse auslassen und sich nur auf die letzteren Punkte konzentrieren. Komplette apidox sehen ungefähr so aus:

<code cppqt>
/** Namespace for KDE network-related classes */
namespace KDENetwork {
/** Wrapper for a TCP/IP socket */
class Socket {
public:
/** Constructor. Calls listen() on some random high port. */
Socket();
private:
int fd;
};
}
</code>

Wie man sieht, ist jede Schachtelungsebene der eben erwähnten "Dinge" mit einem Kommentar versehen -- Der Namensraum, die Klasse und die Methode. Private "Dinge" benötigen keine apidox, protected "Dinge" jedoch schon.

Es ist wichtig, jede einzelne Schachtelungsebene zu dokumentieren, denn läßt man einen Ebene aus, ignoriert Doxygen die inneren ebenso und man findet diese nicht mehr wieder. Angenommen man würde im obigen Beispiel die Klassendokumentation weglassen, dann würde die Dokumentation für die Methode Socket() ebenfalls verschwinden. Das ist eine der typischen Fallen beim Schreiben von apidox.

Und wenn man nur eine Erklärung für jeden Teil seines Programmes schreibt, hat man schon einen großen Teil des Weges zu einer kompletten apidox hinter sich gelassen. Diese Erklärungen zu schreiben macht das Programm einfacher für andere Entwickler zu verstehen und zeigt einem oft schon sub-optimale Designs oder Namenswahlen. Auf diese Art gewinnen beide Seiten.

Man findet in der Liste von unterstützen Tags auch Beispiele für ausgefallenere apidox -- Erklärung von Parametern oder wie man die apidox mit Beispielen und Personendaten versieht. Es lohnt sich auch nachzusehen, wie man apidox aktiviert, doch es ist auch möglich die Arbeit aufzuteilen: Du schreibst die apidox selber und fragst den Originalautor (mailto:groot@kde.org), diese für dein Modul zu aktivieren. Er verspricht (zunmindest in der englischsprachigen Originalversion) das dann zu tun.

== APIDOX in neuem Code schreiben ==

Wenn mann neuen Code schreibt und dabei apidox verwenden möchte, sollte man am besten KDevelop benutzen. Vernünftig konfiguriert kann dieses automatisch ein Grundgerüst für apidox einfügen, man muß dann nur noch die eigentlichen Beschreibungen einfügen. Und man muß sich nicht mehr mit apidox kommandos rumärgern.

Wenn man sich nicht in dieser günstigen Lage befindet, sollte die folgende Checkliste einen durch die schlimmsten Untiefen beim Schreiben von apidox führen:

'''1. Schreibe die apidox direkt mit dem Code zusammen'''

The discipline it takes to write down the apidox for function foo() now as you are thinking of foo() and what it needs to do more than compensates the effort later where you have to remember what foo() was supposed to do, anyway.

This isn't to say you have to do it this way, but it is convenient. The apidox also document design decisions. They also document what you want a particular piece of code to do, regardless of what it actually does. That makes it possible to independently check that the code does what it's supposed to: because it's written down.

'''2. Dokumentierte deine Header vollständig'''

The headers are what's most visible to users (in this context, users are developers who are re-using) of your code, and they should be complete. Document each structural bit of the headers as you go along. This means:

*Every file should have a file-level comment. This is suggested in the KDE guidelines anyway -- near the top of your file, write down what the file is for, vaguely what it defines. Wrap this up in a /** @file */ comment and you are set.
*Every namespace should have a comment. A given namespace only needs a comment once in your source tree (or within one bunch of files that generate apidox together), but it can't hurt to repeat the description on each occasion -- just make it brief. These comments are just plain apidox comments wrapped up in /** */ ; there are no special markups needed like the @file for file comments. Do make sure the comment is just before the namespace and doesn't get distanced from the namespace it documents. The following is fine:
<code cppqt>/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */

namespace Ungulate {
</code>
:In the next example, someone has snuck in some extra stuff between the apidox comment and the namespace it is documenting. This may cause Doxygen errors (so then it is easy to spot) or it may cause the namespace documentation to attach to something wildly different (and then it's hard to spot).
<code cppqt>
/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */
class Mammal;
namespace Ungulate {
</code>
:There is not much you can do about this except to be watching when you insert code -- don't separate apidox from the thing they are documenting.
*Every class should have a comment. Classes are the important building blocks of your application or library, so this is one place where writing lots helps. Write down why the class exists. Write down what it is supposed to do. Give an example of how to use it. Explain how not to use it, or what prerequisites it has (for instance, lots of classes need a KInstance object, but don't document that explicitly). The same caveats apply as with namespace apidox: make sure the class follows its apidox immediately.
*Every method should have a comment explaining what it does and what the parameters are for. Method parameters should be documented using @param. Don't rely on the name of the method or the parameters to be fully self-documenting. Besides, writing these things down properly will trigger Doxygen errors if you change them in an incompatible way later -- and that is going to save you lots of time in finding source and binary incompatibilities and explaining to users why their code suddenly doesn't do what they expect (assuming it compiles at all). So good method apidox is an additional insurance against making bad changes. Same caveats apply.
*Every enumeration type should have a comment explaining what the enumeration is for, even if it's just /** Various constants */.
*Every enumeration value should have a comment too, to explain what it represents. Don't rely on the name of the enumeration value being sufficiently expressive. For the purposes of readability, I suggest that you document enumeration values after the value, as opposed to the documentation format for namespaces, classes and methods where you write the documentation in front of the thing you are documenting. The format of the documentation is slightly different. Instead of writing /** Documentation */ in front, you write /**< Documentation afterards */, where the < denotes that the documentation applies to the thing just past. It looks like this:
<code cppqt>
enum State {
none, /**< No bracket seen */
bracket, /**< Found a ( for grouping */
squote, /**< Found a single quote */
dquote /**< Found double quotes */
};
</code>

'''3. Watch this space!'''

Watch the [http://www.englishbreakfastnetwork.org/ English Breakfast Network] for the [http://www.englishbreakfastnetwork.org/apidocs/ results] of your apidox work. Check the log files for errors -- Doxygen can complain quite loudly.

'''4. Write a main page for your application.'''

This is usually done in a separate file {{path|Mainpage.dox}} in the top-level of a library or application. The file's content is just a single apidox comment that starts with /** @mainpage title ; the rest of the file is just a long comment about what the library or application is for.

== APIDOX in altem Code korrigieren ==

Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)

In old apidox, you are more likely to suffer from the following symptoms:

*Missing parameter documentation (because parameters were renamed, or added, or removed, or something).
*Missing method documentation.
*Missing class documentation.
*Documentation that has wandered off on its own and is attached to the wrong thing now.

The first of these can be fixed by correcting the parameter documentation. See the examples section. The next two -- missing documentation that you can see is there in the source files but that does not show up in the generated HTML pages, is usually a matter of missing documentation on surrounding blocks. See the common pitfalls section, and make sure that the surrounding classes, namespaces and files all have documentation.

The last problem can best be fixed by moving the offending documentation back to where it belongs (really, it's not the documentation that is at fault, it's whatever has squeezed in -- the home-breaker -- between the documentation and the thing it was originally attached to). You could use some Doxygen special tags to avoid moving stuff around like that, but it does not help the understandability of the source much.

== Beispiel APIDOX ==

So what does documentation look like in the headers? How do you write a method documenation that describes the parameters as well? This section contains boilerplate for most common situations. Doxygen does not require a strict style -- it will ignore whitespace and asterisks at the beginning of a line, so you can make the documentation ASCII-pretty.

'''Documentation for a file:''' The newline after @file is significant! The text after @author is listed in a special Authors section of the apidox; you can list multiple authors.

<code cppqt>
/** @file
* This file is part of AnApplication and defines
* classes Ungulate and Moose.
*
* @author Mostly by me
*/
</code>

'''Documentation for a namespace:'''

<code cppqt>
/**
* This namespace collects functions related to
* counting and enumeration of mammals and their limbs.
*/
</code>

'''Documentation for a class:''' Some Doxygen special commands are used here to provide additional information. @author (as with files) identifies authors of the code; these are collected in a special ''Authors:'' section of the apidox. You can list more than one author. The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.

<code cppqt>
/**
* This class represents a Moose in the woodland
* simulator. A single Moose object can be created,
* but it is more useful to instantiate Moose::Factory
* by calling Moose::factory(), and then calling spawn()
* for each new Moose, since that maintains the ecological
* balance far better.
*
* @author Adriaan de Groot <degroot@kde.org>
* @since 3.5
*/
</code>

'''Method documentation:''' We can use @author and @since just like we do for classes. In addition, there are the parameters of the method that can be described. @p is used to refer to them in running text, and @param is used to construct a list of parameter descriptions that is specially formatted. Finally, @return entries describe the values that may be returned by the method.

<code cppqt>
/**
* This method names a particular Moose and as a side effect
* sets whether or not the Moose is treated as a Reindeer.
* When @p santa is @c true, the name of the moose is set to
* the next of the available Reindeer (if possible).
*
* @param name name to assign to the Moose, which is only
* relevant if the moose is not a Reindeer.
* @param santa is this Moose assigned to Santa? if so, the
* name is irrelevant.
*
* @return @c true if naming the Moose succeeded
* @return @c false if naming the Moose failed. This only
* happens if the Moose is assigned to Santa duty
* but there are already eight named Reindeer.
*/
bool name(const QString &name, bool santa = false);
</code>

Enum documentation is described in the section on writing new apidox. The same kind of documentation as for classes applies, with the addition of the documentation for each enumerated value which belongs inline.

== Beliebte Fehler ==

This section lists common pitfalls in writing apidox. Typically, they are easily
overlooked mistakes that produce weird error messages, but I will also include
some stylistic pitfalls that should be avoided.

'''Missing APIDOX''': You ''know'' you wrote dox for class Moose, but after
generation they are not visible. You ''know'' that the file-scope function int
foo() is documented, but it's not there either! What is going on?

The most common pitfall, the one that leads to "missing" apidox, is forgetting
to document surrounding structure. The "structure" in the source comes from
files, namespaces, classes and methods. In order to document a class you must
document the namespace it is in (if there is one) and the file that it is in.
In order to document a method, you must document the class it is in (and thus
the namespace and file). So the easiest rule of thumb is to
document ''everything''.
{{note (de)|This hard-and-fast rule is not quite accurate:
classes do not need the file to be documented,
so you can leave out the /** @file */ comment for
source files containing only classes (and namespaces).
Note that classes in a namespace require the namespace
to be documented, but classes in the :: namespace
don't need extra documentation.
I'm not sure about anonymous namespaces.

For file-scoped functions -- that is, functions
that are defined in a file, not in a namespace
and not in a class,
you ''must'' document the file
they are in. This applies mostly
to files which collect a bunch of non-method utility functions.}}

'''Broken parameter documentation:''' Documenting parameters to methods can be done two ways: you can document none of them, or you can document
''all'' of them for a given method. There is no middle ground (that doesn't
generate gobs of errors that you should fix).

If you document ''all'' of your parameters (which is a good thing to do,
and generates things in a nicely formatted fashion), then your method
apidox consists first of a general description of the method and then a
bunch of @param tags which describe each individual parameter. The @param
tag is followed by the name of the parameter -- watch out for spelling
and case-sensitivity! -- and then the description. The description can
span multiple lines.
<code cppqt>
/** Calculate the root-mean-square distance from the
* origin to the given integral coordinate.
*
* @param y y-coordinate, which is on an axis perpendicular to the
* x-axis, yet still in the same plane.
* @param x x-coordinate
*/
</code>

When you document all the parameters like this, Doxygen will complain if
you misspell parameter names, or forget some, or mention parameters that
are not there. This will force you to update the documentation if you
change the method signature. And that's a good thing.

Additional pitfalls are putting the type of the parameter in the list,
like @param int x, which makes "int" the name of the parameter. Another
pitfall is that @param should come after the general description.
Once the @param list starts, nothing can stop it except for other
list-style Doxygen tags like @since, @author or @return. So write @param
after the story and before, say, @return.

If you document ''none'' of the parameters, you do not use the @param tag
at all. You can talk about your parameters by writing @p before the name
of a parameter (or anything else, really, but it only makes sense in front
of a name of a parameter). Like this:
<code cppqt>
/** Calculate the root-mean-square distance from the origin to
* the given integral coordinate which is given as a pair @p x,
* @p y. If @p nonFree is true, use ESR instead of RMS in the
* computation.
*/
double distance(int x, int y, bool nonFree=false);
</code>

'''Misuse of tags in running text:''' This boils down to the warning
above about where to put @param: not every Doxygen tag can go anywhere.
Some start lists or basically end the general description part of a
description, so you need to avoid using them in running text.

'''Chosing between Doxygen errors and compiler warnings:''' If you are
going to document your parameters, you need to name them. If you are
defining a stub method, this can lead to compiler warnings.

'''Accidental tags:''' It can be easy to accidentally use Doxygen tags
in running text -- email addresses, backslash escapes, those are the
easy ones. Watch the Doxygen logs and escape that at sign with a backslash
when needed (i.e. write \@ to get an at sign). It's probably a good
idea to avoid the backslash style of apidox entirely; at the same time, if
you happen to write \moose, Doxygen will complain that that is an invalid
tag.

'''Accidental HTML:''' If you use < and > in your apidox, these may
confuse Doxygen -- especially if you write things like <service>
which look like HTML tags. This is a common way of writing some kind of
element that may be replaced in a method call or string or something, so
it crops up all the time. You know, you write some thing like this:
<code cppqt>
/** This method connects to a database. The connection string is
* composed of a username, password, host and database name as
* follows:
* <username>:<password>@<host>//<database>
*
* @return true if the connection succeeded.
*/
</code>

This bit of dox is terribly broken, because the whole sample connection
string will be interpreted as (bad) HTML and ignored. There are two
solutions:
<ol>
*Write \< instead of just < to escape the < and make Doxygen output it normally. Doxygen is smart enough to turn this into &lt; in HTML output. This has only a minimal impact on readability of the dox in the header files themselves.
*Use the HTML formatting that Doxygen makes available, and write ''foo'' instead of <foo>. This produces nicer output with italics instead of plain text, so it is easier to spot what is the replaceable part of the text. The downside is that it has a larger visible impact on the apidox in the headers.
</ol>

;Superfluous @ref
:It can be tempting -- certainly if you've written dox for other projects -- to use #method or @ref method to force a reference to another method somewhere. Relax, it's not needed and usually causes Doxygen warnings to boot. Just name the method normally, make apidox and watch the references appear naturally.

== KDE spezifische Tags ==
'''@bc''': This tag indicated binary compatibility, much like ''@since'' does. The argument after ''@bc'' is the scope of binary compatibility (for instance, KDE4). Classes that are not marked with ''@bc'' may, in some modules, be flagged as incompatible so that they can be avoided.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @bc KDE4.2 Compatibility is expected to break
* with next-generation mooses.
*/
</code>

'''@libs''': Use this tag to indicate what libraries should be linked in for the given class. Although this is usually the name of the directory the class lives in, this is not always the case.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @libs
* @a -lkdeui or use \$(LIB_KDEUI) in the KDE build framework.
*/
</code>

== Code Beispiele in APIDOX ==

Es kann nützlich sein, Beispielcode zur APIDOX einer Klasse hinzuzufügen. Sehr nützlich ist es auf jeden Fall für Leser, die sich fragen, wie man eine Klasse genau zu benutzen hat. Die meisten Klassen in {{path|kdelibs/kdecore}} haben Beispielcode.

Ein Weg, um Beispielcode zu schreiben ist es, @code und @endcode um den Block des Beispielcodes in den Doxygenkommentaren selber zu legen, wie im folgenden Beispiel:
<code cppqt>
/**
* This class represents a Moose.
* The correct way of generating Meese is to use the factory:
*
* @code
* Moose::Factory outlet = Moose::factory();
* Moose *m = outlet.spawn();
* @endcode
*/
</code>

Auf diese Art wird es in den meisten Beispielen in {{path|kdelibs}} gemacht. Das funktioniert auch ganz gut, man kann sich bei den Beispielen aufs wesentliche beschränken.

Ein wichtiges Problem dieser Herangehensweise um Beispielcode zu schreiben ist es, dass der Code niemals geprüft wird, ob er wirklich funktioniert. Die meisten Codebeispiele sind so gepackt, dass es schwer ist, diese in einen funktionsfähigen Code umzuschreiben, der wirklich kompiliert und läuft.

Um dieses Problem zu lösen, kann man ''richtigen Code'' schreiben, der wirklich kompiliert (als Teil dr Test-Suite für den Code, den man sowieso hat) und exakt beschreibt, wie eine Klasse in einem richtigen Programm benutzt werden soll. Man muß jedoch nicht den gesamten Code in die APIDOX übernehmen, sondern braucht nur die interessanten Teile zu markieren. Um das zu bewerkstelligen, wird eine Datei in das <tt>tests</tt> Unterverzeichnis eingefügt. Dann kann man das Doxygen @include-Tag benutzen, um den Code dieser Datei in die API Dokumentation zu übernehmen.

{{warning (de)|Benutze nicht @example! Es macht etwas total anderes als was du erwarten könntest (zum Beispiel fügt es keinen Beispiel-Code ein).}}

== Links ==

[http://www.stack.nl/~dimitri/doxygen/commands.html englische Liste der unterstützen Doxygen Tags]
:Hier ist eine Liste von allen verfügbaren Dokumentations-Tags von Doxygen von der offiziellen Seite. Beachte, das diese Seite ein Backslash vor einem Tag benutzt, während diese Seite immer das At-Zeichen benutzt. Beides ist erlaubt, doch in KDE sollte zu Gunsten der Konsistenz das At-Zeichen benutzt werden.

[[Category:Documentation]]

Development/Tutorials/API Documentation (de)

2008-11-01T15:39:40Z

DrSlowDecay: More translation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/API Documentation}}
__TOC__
{{Box|Definition|
'''API (''Application Programming Interface'') Dokumentation''' ist die Dokumentation eines ''Programmes'' und seiner Schnittstellen. Durch Dokumentation wird einem Entwickler, der mit oder an dem Programm arbeitet, erklärt, wie Dinge funktionieren und wie und welche Methoden aufzurufen sind.

API Dokumentation wird machmal auch API Referenz Handbuch (API reference manual) genannt. Es muß nicht ''nur'' ein Referenz Handbuch sein, obwohl es umfangreiches zusätzliches Material, wie Anleitungen, Zeitleisten, etc., enthalten kann. Auf dieser Seite wird alles Material welches die API eines Codes dokumentiert und erklärt "apidox" genannt.

Gute apidox benötigt etwas Mühe zum schreiben -- doch sicherlich weniger Mühe als gute ''Benutzer'' Dokumentation, da du als Entwickler für andere Entwickler schreibst und eklärst wie Code funktioniert und was er tun soll. So dein Publikum ist bereit damit zu arbeiten. Der Vorteil von apidox zeigt sich, wenn jemand anderes (oder sogar du selbst einige Monate später) den Code (wieder)verwenden oder erweitern möchte. Gute apidox bedeutet, dass jemand neues kommen kann, den Code schnell versteht und nützliche Patches erstellen kann. Gerade für Bibliotheken kann apidox es ermöglichen, diese wie eine Black Box zu benutzen (und so sollte es auch sein), da die benötigte Dokumentation vorliegt und die Dokumentation sich nicht in den tiefen des (vielleicht gar nicht vorliegenden) C codes befindet.|100%}}

== Vorwort ==

Mit APIDOX wird es anderen Entwicklern ermöglicht, auf ein Programm zuzugreifen. Sie sind nicht unbedingt notwenig doch sie helfen neuen Leuten, die an dem Programm arebeiten möchten oder den Code ohne große Änderungen wiederverwenden möchten, sicherlich eine Menge.

Ein Blick auf [http://doc.trolltech.com/latest/ die Qt Dokumentation (englisch)] ermöglicht es, einen Eindruck von guter apidox Dokumentation zu bekommen. Dort sieht man eine Stilkonsistenz, die sich durch die gesamte Dokumentation zieht. Dadurch kann man eine Menge über Qt lernen, nur indem man die Dokumentation liest. Es ist nicht notwendig, die Anleitungsprogramme auszuführen oder den Quellcode zu lesen um herauszufinden, was ein Parameter in einer bestimmten Methode einer Bibliothek macht. Es wird alles bereits erläutert.

Apidox zu schreiben besteht aus zwei Teilen. Der erste Teil ist technischer Natur: Man muß den Code verstehen, der dokumentiert werden soll, oder zumindest wissen, was er tun soll und wie er benutzt werden muss. Der andere Teil ist reine Disziplin: apidox ist am nützlichsten, wenn es sorgfältig und ausführlich benutzt wird.

Dieses Dokument versucht den apidox Prozess nicht zu ausführlich werden zu lassen, indem es einige dirkekte Tips gibt, wie man apidox schreibt. Es gibt dann doch die [[Policies/Library Documentation Policy|library apidox policies (englisch)]], die sehr viel strenger sind. Es schadet nicht, auch dort mal einen Blick reinzuwerfen.

{{note (de)|Die eigentliche Beispieldokumentation auf dieser Seite wird nicht übersetzt, da API Dokumentation in der Regel auf englisch verfasst werden, um eine internationale Mitarbeit zu ermöglichen}}

== APIDOX Basics ==

APIDOX werden durch das [http://www.doxygen.org Doxygen] Dokumentationswerkzeug verarbeitet. Dieses Werkzeug liest den Quellcode der Applikation (oder Bibliothek) und erzeugt schön formatierte Dokumentation daraus. Es gibt ein gutes [http://www.stack.nl/~dimitri/doxygen/manual.html Referenz Handbuch (auf englisch)] -- doch für die Grundlagen muß dieses nicht vollständig gelesen werden.

{{Tip|Doxygen muß für die Arbeit an apidox der Applikation nicht installiert sein. Alle paar Stunden erzeugt das [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] apidox für alle bekannten KDE Module. Logfiles und die eigentlichen Apidox werden ebenfalls bereitgestellt, um Fehlermeldungen zu entdecken und diese zu beheben. Das ist zwar nicht die schellste Methode apidox zu schreiben und zu korrigieren, doch es erledigt diese Aufgabe. Ein paar Stunden Arbeit am Tag, um an der apidox zu arbeiten, reichen aus.}}

{{Tip|Hast du Doxygen installiert und möchtest die apidox erzeugen, benutze das kdedoxygen.sh Skript wie es in [[Development/Tools/apidox|apidox (englisch)]] beschrieben ist.}}

Die Grundlagen von apidox sind einfach und machen Spaß: Man schreibt einfach Kommentare in den Code, die erklären wofür dieser ist. Diese Kommetare sind fast das gleiche wie das, was man sowieso in die header des Codes schreiben muß, so ist das ganze also nicht so schwer.

APIDOX werden in speziellen Kommentaren geschrieben. Diese Kommentare starten mit /** (Schrägstrich, Stern, Stern) -- und das ist es, was sie besonders macht. Der Rest des Kommentars ist einfacher Text, der den Teil des Programms beschreibt. Dieser Text wird vom Doxygen Prozessor interpretiert, damit dadurch passende Beschreibungen der Parameter und Rückgabewerte erfolgen kann. Doch die Dokumentation ist recht unkompliziert: Man schreibt einfach, was eine Methode tut innerhalb von /** und */, so wie folgendes Beispiel:

<code cppqt>
/** This method increases the sexyness of Kontact and should as
* such be called whenever possible (i.e. instead of having idle
* time, you might think of calling this method and helping
* Kontact gain even more popularity). You might even insert it
* into your own event loop to ensure it is called as often as
* possible. If these calls decrease the number of new features,
* it's still no problem to call it.
*/
void incSexyness(KInstance *instance);
</code>

Für eine vernünftige apidox muß jedes "Ding" des Programms dokumentiert werden. "Dinge" sind hierbei Verzeichnisse, Dateien, Namensräume, Klassen, Methoden, Aufzählungen und Variablen. Man kann eventuell Dateien und Verzeichnisse auslassen und sich nur auf die letzteren Punkte konzentrieren. Komplette apidox sehen ungefähr so aus:

<code cppqt>
/** Namespace for KDE network-related classes */
namespace KDENetwork {
/** Wrapper for a TCP/IP socket */
class Socket {
public:
/** Constructor. Calls listen() on some random high port. */
Socket();
private:
int fd;
};
}
</code>

Wie man sieht, ist jede Schachtelungsebene der eben erwähnten "Dinge" mit einem Kommentar versehen -- Der Namensraum, die Klasse und die Methode. Private "Dinge" benötigen keine apidox, protected "Dinge" jedoch schon.

Es ist wichtig, jede einzelne Schachtelungsebene zu dokumentieren, denn läßt man einen Ebene aus, ignoriert Doxygen die inneren ebenso und man findet diese nicht mehr wieder. Angenommen man würde im obigen Beispiel die Klassendokumentation weglassen, dann würde die Dokumentation für die Methode Socket() ebenfalls verschwinden. Das ist eine der typischen Fallen beim Schreiben von apidox.

Und wenn man nur eine Erklärung für jeden Teil seines Programmes schreibt, hat man schon einen großen Teil des Weges zu einer kompletten apidox hinter sich gelassen. Diese Erklärungen zu schreiben macht das Programm einfacher für andere Entwickler zu verstehen und zeigt einem oft schon sub-optimale Designs oder Namenswahlen. Auf diese Art gewinnen beide Seiten.

Man findet in der Liste von unterstützen Tags auch Beispiele für ausgefallenere apidox -- Erklärung von Parametern oder wie man die apidox mit Beispielen und Personendaten versieht. Es lohnt sich auch nachzusehen, wie man apidox aktiviert, doch es ist auch möglich die Arbeit aufzuteilen: Du schreibst die apidox selber und fragst den Originalautor (mailto:groot@kde.org), diese für dein Modul zu aktivieren. Er verspricht (zunmindest in der englischsprachigen Originalversion) das dann zu tun.

== APIDOX in neuem Code schreiben ==

Wenn mann neuen Code schreibt und dabei apidox verwenden möchte, sollte man am besten KDevelop benutzen. Vernünftig konfiguriert kann dieses automatisch ein Grundgerüst für apidox einfügen, man muß dann nur noch die eigentlichen Beschreibungen einfügen. Und man muß sich nicht mehr mit apidox kommandos rumärgern.

Wenn man sich nicht in dieser günstigen Lage befindet, sollte die folgende Checkliste einen durch die schlimmsten Untiefen beim Schreiben von apidox führen:

'''1. Schreibe die apidox direkt mit dem Code zusammen'''

The discipline it takes to write down the apidox for function foo() now as you are thinking of foo() and what it needs to do more than compensates the effort later where you have to remember what foo() was supposed to do, anyway.

This isn't to say you have to do it this way, but it is convenient. The apidox also document design decisions. They also document what you want a particular piece of code to do, regardless of what it actually does. That makes it possible to independently check that the code does what it's supposed to: because it's written down.

'''2. Dokumentierte deine Header vollständig'''

The headers are what's most visible to users (in this context, users are developers who are re-using) of your code, and they should be complete. Document each structural bit of the headers as you go along. This means:

*Every file should have a file-level comment. This is suggested in the KDE guidelines anyway -- near the top of your file, write down what the file is for, vaguely what it defines. Wrap this up in a /** @file */ comment and you are set.
*Every namespace should have a comment. A given namespace only needs a comment once in your source tree (or within one bunch of files that generate apidox together), but it can't hurt to repeat the description on each occasion -- just make it brief. These comments are just plain apidox comments wrapped up in /** */ ; there are no special markups needed like the @file for file comments. Do make sure the comment is just before the namespace and doesn't get distanced from the namespace it documents. The following is fine:
<code cppqt>/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */

namespace Ungulate {
</code>
:In the next example, someone has snuck in some extra stuff between the apidox comment and the namespace it is documenting. This may cause Doxygen errors (so then it is easy to spot) or it may cause the namespace documentation to attach to something wildly different (and then it's hard to spot).
<code cppqt>
/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */
class Mammal;
namespace Ungulate {
</code>
:There is not much you can do about this except to be watching when you insert code -- don't separate apidox from the thing they are documenting.
*Every class should have a comment. Classes are the important building blocks of your application or library, so this is one place where writing lots helps. Write down why the class exists. Write down what it is supposed to do. Give an example of how to use it. Explain how not to use it, or what prerequisites it has (for instance, lots of classes need a KInstance object, but don't document that explicitly). The same caveats apply as with namespace apidox: make sure the class follows its apidox immediately.
*Every method should have a comment explaining what it does and what the parameters are for. Method parameters should be documented using @param. Don't rely on the name of the method or the parameters to be fully self-documenting. Besides, writing these things down properly will trigger Doxygen errors if you change them in an incompatible way later -- and that is going to save you lots of time in finding source and binary incompatibilities and explaining to users why their code suddenly doesn't do what they expect (assuming it compiles at all). So good method apidox is an additional insurance against making bad changes. Same caveats apply.
*Every enumeration type should have a comment explaining what the enumeration is for, even if it's just /** Various constants */.
*Every enumeration value should have a comment too, to explain what it represents. Don't rely on the name of the enumeration value being sufficiently expressive. For the purposes of readability, I suggest that you document enumeration values after the value, as opposed to the documentation format for namespaces, classes and methods where you write the documentation in front of the thing you are documenting. The format of the documentation is slightly different. Instead of writing /** Documentation */ in front, you write /**< Documentation afterards */, where the < denotes that the documentation applies to the thing just past. It looks like this:
<code cppqt>
enum State {
none, /**< No bracket seen */
bracket, /**< Found a ( for grouping */
squote, /**< Found a single quote */
dquote /**< Found double quotes */
};
</code>

'''3. Watch this space!'''

Watch the [http://www.englishbreakfastnetwork.org/ English Breakfast Network] for the [http://www.englishbreakfastnetwork.org/apidocs/ results] of your apidox work. Check the log files for errors -- Doxygen can complain quite loudly.

'''4. Write a main page for your application.'''

This is usually done in a separate file {{path|Mainpage.dox}} in the top-level of a library or application. The file's content is just a single apidox comment that starts with /** @mainpage title ; the rest of the file is just a long comment about what the library or application is for.

== APIDOX in altem Code korrigieren ==

Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)

In old apidox, you are more likely to suffer from the following symptoms:

*Missing parameter documentation (because parameters were renamed, or added, or removed, or something).
*Missing method documentation.
*Missing class documentation.
*Documentation that has wandered off on its own and is attached to the wrong thing now.

The first of these can be fixed by correcting the parameter documentation. See the examples section. The next two -- missing documentation that you can see is there in the source files but that does not show up in the generated HTML pages, is usually a matter of missing documentation on surrounding blocks. See the common pitfalls section, and make sure that the surrounding classes, namespaces and files all have documentation.

The last problem can best be fixed by moving the offending documentation back to where it belongs (really, it's not the documentation that is at fault, it's whatever has squeezed in -- the home-breaker -- between the documentation and the thing it was originally attached to). You could use some Doxygen special tags to avoid moving stuff around like that, but it does not help the understandability of the source much.

== Beispiel APIDOX ==

So what does documentation look like in the headers? How do you write a method documenation that describes the parameters as well? This section contains boilerplate for most common situations. Doxygen does not require a strict style -- it will ignore whitespace and asterisks at the beginning of a line, so you can make the documentation ASCII-pretty.

'''Documentation for a file:''' The newline after @file is significant! The text after @author is listed in a special Authors section of the apidox; you can list multiple authors.

<code cppqt>
/** @file
* This file is part of AnApplication and defines
* classes Ungulate and Moose.
*
* @author Mostly by me
*/
</code>

'''Documentation for a namespace:'''

<code cppqt>
/**
* This namespace collects functions related to
* counting and enumeration of mammals and their limbs.
*/
</code>

'''Documentation for a class:''' Some Doxygen special commands are used here to provide additional information. @author (as with files) identifies authors of the code; these are collected in a special ''Authors:'' section of the apidox. You can list more than one author. The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.

<code cppqt>
/**
* This class represents a Moose in the woodland
* simulator. A single Moose object can be created,
* but it is more useful to instantiate Moose::Factory
* by calling Moose::factory(), and then calling spawn()
* for each new Moose, since that maintains the ecological
* balance far better.
*
* @author Adriaan de Groot <degroot@kde.org>
* @since 3.5
*/
</code>

'''Method documentation:''' We can use @author and @since just like we do for classes. In addition, there are the parameters of the method that can be described. @p is used to refer to them in running text, and @param is used to construct a list of parameter descriptions that is specially formatted. Finally, @return entries describe the values that may be returned by the method.

<code cppqt>
/**
* This method names a particular Moose and as a side effect
* sets whether or not the Moose is treated as a Reindeer.
* When @p santa is @c true, the name of the moose is set to
* the next of the available Reindeer (if possible).
*
* @param name name to assign to the Moose, which is only
* relevant if the moose is not a Reindeer.
* @param santa is this Moose assigned to Santa? if so, the
* name is irrelevant.
*
* @return @c true if naming the Moose succeeded
* @return @c false if naming the Moose failed. This only
* happens if the Moose is assigned to Santa duty
* but there are already eight named Reindeer.
*/
bool name(const QString &name, bool santa = false);
</code>

Enum documentation is described in the section on writing new apidox. The same kind of documentation as for classes applies, with the addition of the documentation for each enumerated value which belongs inline.

== Beliebte Fehler ==

This section lists common pitfalls in writing apidox. Typically, they are easily
overlooked mistakes that produce weird error messages, but I will also include
some stylistic pitfalls that should be avoided.

'''Missing APIDOX''': You ''know'' you wrote dox for class Moose, but after
generation they are not visible. You ''know'' that the file-scope function int
foo() is documented, but it's not there either! What is going on?

The most common pitfall, the one that leads to "missing" apidox, is forgetting
to document surrounding structure. The "structure" in the source comes from
files, namespaces, classes and methods. In order to document a class you must
document the namespace it is in (if there is one) and the file that it is in.
In order to document a method, you must document the class it is in (and thus
the namespace and file). So the easiest rule of thumb is to
document ''everything''.
{{note (de)|This hard-and-fast rule is not quite accurate:
classes do not need the file to be documented,
so you can leave out the /** @file */ comment for
source files containing only classes (and namespaces).
Note that classes in a namespace require the namespace
to be documented, but classes in the :: namespace
don't need extra documentation.
I'm not sure about anonymous namespaces.

For file-scoped functions -- that is, functions
that are defined in a file, not in a namespace
and not in a class,
you ''must'' document the file
they are in. This applies mostly
to files which collect a bunch of non-method utility functions.}}

'''Broken parameter documentation:''' Documenting parameters to methods can be done two ways: you can document none of them, or you can document
''all'' of them for a given method. There is no middle ground (that doesn't
generate gobs of errors that you should fix).

If you document ''all'' of your parameters (which is a good thing to do,
and generates things in a nicely formatted fashion), then your method
apidox consists first of a general description of the method and then a
bunch of @param tags which describe each individual parameter. The @param
tag is followed by the name of the parameter -- watch out for spelling
and case-sensitivity! -- and then the description. The description can
span multiple lines.
<code cppqt>
/** Calculate the root-mean-square distance from the
* origin to the given integral coordinate.
*
* @param y y-coordinate, which is on an axis perpendicular to the
* x-axis, yet still in the same plane.
* @param x x-coordinate
*/
</code>

When you document all the parameters like this, Doxygen will complain if
you misspell parameter names, or forget some, or mention parameters that
are not there. This will force you to update the documentation if you
change the method signature. And that's a good thing.

Additional pitfalls are putting the type of the parameter in the list,
like @param int x, which makes "int" the name of the parameter. Another
pitfall is that @param should come after the general description.
Once the @param list starts, nothing can stop it except for other
list-style Doxygen tags like @since, @author or @return. So write @param
after the story and before, say, @return.

If you document ''none'' of the parameters, you do not use the @param tag
at all. You can talk about your parameters by writing @p before the name
of a parameter (or anything else, really, but it only makes sense in front
of a name of a parameter). Like this:
<code cppqt>
/** Calculate the root-mean-square distance from the origin to
* the given integral coordinate which is given as a pair @p x,
* @p y. If @p nonFree is true, use ESR instead of RMS in the
* computation.
*/
double distance(int x, int y, bool nonFree=false);
</code>

'''Misuse of tags in running text:''' This boils down to the warning
above about where to put @param: not every Doxygen tag can go anywhere.
Some start lists or basically end the general description part of a
description, so you need to avoid using them in running text.

'''Chosing between Doxygen errors and compiler warnings:''' If you are
going to document your parameters, you need to name them. If you are
defining a stub method, this can lead to compiler warnings.

'''Accidental tags:''' It can be easy to accidentally use Doxygen tags
in running text -- email addresses, backslash escapes, those are the
easy ones. Watch the Doxygen logs and escape that at sign with a backslash
when needed (i.e. write \@ to get an at sign). It's probably a good
idea to avoid the backslash style of apidox entirely; at the same time, if
you happen to write \moose, Doxygen will complain that that is an invalid
tag.

'''Accidental HTML:''' If you use < and > in your apidox, these may
confuse Doxygen -- especially if you write things like <service>
which look like HTML tags. This is a common way of writing some kind of
element that may be replaced in a method call or string or something, so
it crops up all the time. You know, you write some thing like this:
<code cppqt>
/** This method connects to a database. The connection string is
* composed of a username, password, host and database name as
* follows:
* <username>:<password>@<host>//<database>
*
* @return true if the connection succeeded.
*/
</code>

This bit of dox is terribly broken, because the whole sample connection
string will be interpreted as (bad) HTML and ignored. There are two
solutions:
<ol>
*Write \< instead of just < to escape the < and make Doxygen output it normally. Doxygen is smart enough to turn this into &lt; in HTML output. This has only a minimal impact on readability of the dox in the header files themselves.
*Use the HTML formatting that Doxygen makes available, and write ''foo'' instead of <foo>. This produces nicer output with italics instead of plain text, so it is easier to spot what is the replaceable part of the text. The downside is that it has a larger visible impact on the apidox in the headers.
</ol>

;Superfluous @ref
:It can be tempting -- certainly if you've written dox for other projects -- to use #method or @ref method to force a reference to another method somewhere. Relax, it's not needed and usually causes Doxygen warnings to boot. Just name the method normally, make apidox and watch the references appear naturally.

== KDE spezifische Tags ==
'''@bc''': This tag indicated binary compatibility, much like ''@since'' does. The argument after ''@bc'' is the scope of binary compatibility (for instance, KDE4). Classes that are not marked with ''@bc'' may, in some modules, be flagged as incompatible so that they can be avoided.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @bc KDE4.2 Compatibility is expected to break
* with next-generation mooses.
*/
</code>

'''@libs''': Use this tag to indicate what libraries should be linked in for the given class. Although this is usually the name of the directory the class lives in, this is not always the case.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @libs
* @a -lkdeui or use \$(LIB_KDEUI) in the KDE build framework.
*/
</code>

== Code Beispiele in APIDOX ==

It can be useful to put example code in the APIDOX for a class.
Very useful, in fact, for the reader who is wondering
how exactly to use the class in a straightforward way.
Most classes in {{path|kdelibs/kdecore}} have example code.

One way to write example code is to use @code and @endcode around
blocks of example code in the Doxygen comments themselves, like this:
<code cppqt>
/**
* This class represents a Moose.
* The correct way of generating Meese is to use the factory:
*
* @code
* Moose::Factory outlet = Moose::factory();
* Moose *m = outlet.spawn();
* @endcode
*/
</code>

This is how most of the examples in {{path|kdelibs}}
are done, actually. It works reasonably well, you can pare the
example down to something really minimal and leave out all the
boilerplate.

An important drawback of this approach to writing example code is that
the code is never checked to see if it actually works.
The code is also ''so'' terse, usually, that it's hard
to expand into a complete example that actually compiles and runs.

To solve this problem, you can write ''real code'' that
actually compiles (as part of the test suite for the code
that you have anyway) and that illustrates exactly
how to use the class under consideration in an actual program.
Better yet, you do not need to include ''all'' the code
in the APIDOX, just the interesting bits.
The way to do this is to put the code in a file in the
<tt>tests/</tt> subdirectory of your code.
Then use Doxygen's @include tag to include the
code from that file into the API documentation.

{{warning (de)|Benutze nicht @example! Es macht etwas total anderes als was du erwarten könntest (zum Beispiel fügt es keinen Beispiel-Code ein).}}

== Links ==

[http://www.stack.nl/~dimitri/doxygen/commands.html englische Liste der unterstützen Doxygen Tags]
:Hier ist eine Liste von allen verfügbaren Dokumentations-Tags von Doxygen von der offiziellen Seite. Beachte, das diese Seite ein Backslash vor einem Tag benutzt, während diese Seite immer das At-Zeichen benutzt. Beides ist erlaubt, doch in KDE sollte zu Gunsten der Konsistenz das At-Zeichen benutzt werden.

[[Category:Documentation]]

Development/Tutorials/API Documentation (de)

2008-11-01T11:20:50Z

DrSlowDecay: More translation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/API Documentation}}
__TOC__
{{Box|Definition|
'''API (''Application Programming Interface'') Dokumentation''' ist die Dokumentation eines ''Programmes'' und seiner Schnittstellen. Durch Dokumentation wird einem Entwickler, der mit oder an dem Programm arbeitet, erklärt, wie Dinge funktionieren und wie und welche Methoden aufzurufen sind.

API Dokumentation wird machmal auch API Referenz Handbuch (API reference manual) genannt. Es muß nicht ''nur'' ein Referenz Handbuch sein, obwohl es umfangreiches zusätzliches Material, wie Anleitungen, Zeitleisten, etc., enthalten kann. Auf dieser Seite wird alles Material welches die API eines Codes dokumentiert und erklärt "apidox" genannt.

Gute apidox benötigt etwas Mühe zum schreiben -- doch sicherlich weniger Mühe als gute ''Benutzer'' Dokumentation, da du als Entwickler für andere Entwickler schreibst und eklärst wie Code funktioniert und was er tun soll. So dein Publikum ist bereit damit zu arbeiten. Der Vorteil von apidox zeigt sich, wenn jemand anderes (oder sogar du selbst einige Monate später) den Code (wieder)verwenden oder erweitern möchte. Gute apidox bedeutet, dass jemand neues kommen kann, den Code schnell versteht und nützliche Patches erstellen kann. Gerade für Bibliotheken kann apidox es ermöglichen, diese wie eine Black Box zu benutzen (und so sollte es auch sein), da die benötigte Dokumentation vorliegt und die Dokumentation sich nicht in den tiefen des (vielleicht gar nicht vorliegenden) C codes befindet.|100%}}

== Vorwort ==

Mit APIDOX wird es anderen Entwicklern ermöglicht, auf ein Programm zuzugreifen. Sie sind nicht unbedingt notwenig doch sie helfen neuen Leuten, die an dem Programm arebeiten möchten oder den Code ohne große Änderungen wiederverwenden möchten, sicherlich eine Menge.

Ein Blick auf [http://doc.trolltech.com/latest/ die Qt Dokumentation (englisch)] ermöglicht es, einen Eindruck von guter apidox Dokumentation zu bekommen. Dort sieht man eine Stilkonsistenz, die sich durch die gesamte Dokumentation zieht. Dadurch kann man eine Menge über Qt lernen, nur indem man die Dokumentation liest. Es ist nicht notwendig, die Anleitungsprogramme auszuführen oder den Quellcode zu lesen um herauszufinden, was ein Parameter in einer bestimmten Methode einer Bibliothek macht. Es wird alles bereits erläutert.

Apidox zu schreiben besteht aus zwei Teilen. Der erste Teil ist technischer Natur: Man muß den Code verstehen, der dokumentiert werden soll, oder zumindest wissen, was er tun soll und wie er benutzt werden muss. Der andere Teil ist reine Disziplin: apidox ist am nützlichsten, wenn es sorgfältig und ausführlich benutzt wird.

Dieses Dokument versucht den apidox Prozess nicht zu ausführlich werden zu lassen, indem es einige dirkekte Tips gibt, wie man apidox schreibt. Es gibt dann doch die [[Policies/Library Documentation Policy|library apidox policies (englisch)]], die sehr viel strenger sind. Es schadet nicht, auch dort mal einen Blick reinzuwerfen.

{{note (de)|Die eigentliche Beispieldokumentation auf dieser Seite wird nicht übersetzt, da API Dokumentation in der Regel auf englisch verfasst werden, um eine internationale Mitarbeit zu ermöglichen}}

== APIDOX Basics ==

APIDOX werden durch das [http://www.doxygen.org Doxygen] Dokumentationswerkzeug verarbeitet. Dieses Werkzeug liest den Quellcode der Applikation (oder Bibliothek) und erzeugt schön formatierte Dokumentation daraus. Es gibt ein gutes [http://www.stack.nl/~dimitri/doxygen/manual.html Referenz Handbuch (auf englisch)] -- doch für die Grundlagen muß dieses nicht vollständig gelesen werden.

{{Tip|Doxygen muß für die Arbeit an apidox der Applikation nicht installiert sein. Alle paar Stunden erzeugt das [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] apidox für alle bekannten KDE Module. Logfiles und die eigentlichen Apidox werden ebenfalls bereitgestellt, um Fehlermeldungen zu entdecken und diese zu beheben. Das ist zwar nicht die schellste Methode apidox zu schreiben und zu korrigieren, doch es erledigt diese Aufgabe. Ein paar Stunden Arbeit am Tag, um an der apidox zu arbeiten, reichen aus.}}

{{Tip|Hast du Doxygen installiert und möchtest die apidox erzeugen, benutze das kdedoxygen.sh Skript wie es in [[Development/Tools/apidox|apidox (englisch)]] beschrieben ist.}}

Basic apidox are fun and simple: you write comments in your code explaining what things are supposed to be for. These comments are nearly indistinguishable from stuff you would be writing in the headers of your code ''anyway'', so that's not hard to do.

APIDOX are written in special comments. These comments start with /** (slash, star, star) -- that's what makes them special. The rest of the content of the comment is just plain text describing a part of your program. The plain text is interpreted by the Doxygen processor, so that you can write accurate descriptions of parameters, return types, and do some basic text markup. But documentation can be very straighforward: just write down what a method does, surrounded by /** and */, like this:

<code cppqt>
/** This method increases the sexyness of Kontact and should as
* such be called whenever possible (i.e. instead of having idle
* time, you might think of calling this method and helping
* Kontact gain even more popularity). You might even insert it
* into your own event loop to ensure it is called as often as
* possible. If these calls decrease the number of new features,
* it's still no problem to call it.
*/
void incSexyness(KInstance *instance);
</code>

For proper apidox, you need to document every "thing" in your program. "Things" here are directories, files, namespaces, classes, methods, enums, and member variables. You can actually leave out files and directories, and concentrate on the latter. Complete apidox looks something like this:

<code cppqt>
/** Namespace for KDE network-related classes */
namespace KDENetwork {
/** Wrapper for a TCP/IP socket */
class Socket {
public:
/** Constructor. Calls listen() on some random high port. */
Socket();
private:
int fd;
};
}
</code>

You can see here that each nesting level of "things" is documented with a comment -- the namespace, the class and the method. Things that are private do not need apidox, but things that are protected do.

It is important to document each level of nesting, because if you leave one level out, Doxygen will ignore the documentation in inner nesting levels, and you will be left wondering where it has gone. For instance, if we leave out the class documentation, then the method documentation for Socket() will vanish as well. This is one of the common pitfalls to writing apidox.

If you just do this -- write an explanation for every part of your program -- then you're already a long way on the road to having complete apidox. Writing all those explanations makes your program more accessible to other developers -- and often shows you where the design or choice of names is sub-optimal. So it's a win for you both ways.

You can consult the list of supported tags for examples of more fancy apidox -- explaining parameters, for instance, and annotating the apidox with credits and examples. It's also worthwhile to take a look at the section on enabling apidox, but it's also fine to divide the work: you write the apidox themselves, and ask me (mailto:groot@kde.org) to enable apidox generation for your module. And I will.

== APIDOX in neuem Code schreiben ==

If you are writing new code and want to write apidox, use KDevelop. Really. Properly configured, it can automatically set up all the skeletons for apidox that you need, and what you do is write the descriptions. No messing with apidox commands.

If you're not in that fortunate position, the following little checklist should get you through the worst of writing apidox.

'''1. Write apidox as you code'''

The discipline it takes to write down the apidox for function foo() now as you are thinking of foo() and what it needs to do more than compensates the effort later where you have to remember what foo() was supposed to do, anyway.

This isn't to say you have to do it this way, but it is convenient. The apidox also document design decisions. They also document what you want a particular piece of code to do, regardless of what it actually does. That makes it possible to independently check that the code does what it's supposed to: because it's written down.

'''2. Document your headers completely'''

The headers are what's most visible to users (in this context, users are developers who are re-using) of your code, and they should be complete. Document each structural bit of the headers as you go along. This means:

*Every file should have a file-level comment. This is suggested in the KDE guidelines anyway -- near the top of your file, write down what the file is for, vaguely what it defines. Wrap this up in a /** @file */ comment and you are set.
*Every namespace should have a comment. A given namespace only needs a comment once in your source tree (or within one bunch of files that generate apidox together), but it can't hurt to repeat the description on each occasion -- just make it brief. These comments are just plain apidox comments wrapped up in /** */ ; there are no special markups needed like the @file for file comments. Do make sure the comment is just before the namespace and doesn't get distanced from the namespace it documents. The following is fine:
<code cppqt>/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */

namespace Ungulate {
</code>
:In the next example, someone has snuck in some extra stuff between the apidox comment and the namespace it is documenting. This may cause Doxygen errors (so then it is easy to spot) or it may cause the namespace documentation to attach to something wildly different (and then it's hard to spot).
<code cppqt>
/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */
class Mammal;
namespace Ungulate {
</code>
:There is not much you can do about this except to be watching when you insert code -- don't separate apidox from the thing they are documenting.
*Every class should have a comment. Classes are the important building blocks of your application or library, so this is one place where writing lots helps. Write down why the class exists. Write down what it is supposed to do. Give an example of how to use it. Explain how not to use it, or what prerequisites it has (for instance, lots of classes need a KInstance object, but don't document that explicitly). The same caveats apply as with namespace apidox: make sure the class follows its apidox immediately.
*Every method should have a comment explaining what it does and what the parameters are for. Method parameters should be documented using @param. Don't rely on the name of the method or the parameters to be fully self-documenting. Besides, writing these things down properly will trigger Doxygen errors if you change them in an incompatible way later -- and that is going to save you lots of time in finding source and binary incompatibilities and explaining to users why their code suddenly doesn't do what they expect (assuming it compiles at all). So good method apidox is an additional insurance against making bad changes. Same caveats apply.
*Every enumeration type should have a comment explaining what the enumeration is for, even if it's just /** Various constants */.
*Every enumeration value should have a comment too, to explain what it represents. Don't rely on the name of the enumeration value being sufficiently expressive. For the purposes of readability, I suggest that you document enumeration values after the value, as opposed to the documentation format for namespaces, classes and methods where you write the documentation in front of the thing you are documenting. The format of the documentation is slightly different. Instead of writing /** Documentation */ in front, you write /**< Documentation afterards */, where the < denotes that the documentation applies to the thing just past. It looks like this:
<code cppqt>
enum State {
none, /**< No bracket seen */
bracket, /**< Found a ( for grouping */
squote, /**< Found a single quote */
dquote /**< Found double quotes */
};
</code>

'''3. Watch this space!'''

Watch the [http://www.englishbreakfastnetwork.org/ English Breakfast Network] for the [http://www.englishbreakfastnetwork.org/apidocs/ results] of your apidox work. Check the log files for errors -- Doxygen can complain quite loudly.

'''4. Write a main page for your application.'''

This is usually done in a separate file {{path|Mainpage.dox}} in the top-level of a library or application. The file's content is just a single apidox comment that starts with /** @mainpage title ; the rest of the file is just a long comment about what the library or application is for.

== APIDOX in altem Code korrigieren ==

Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)

In old apidox, you are more likely to suffer from the following symptoms:

*Missing parameter documentation (because parameters were renamed, or added, or removed, or something).
*Missing method documentation.
*Missing class documentation.
*Documentation that has wandered off on its own and is attached to the wrong thing now.

The first of these can be fixed by correcting the parameter documentation. See the examples section. The next two -- missing documentation that you can see is there in the source files but that does not show up in the generated HTML pages, is usually a matter of missing documentation on surrounding blocks. See the common pitfalls section, and make sure that the surrounding classes, namespaces and files all have documentation.

The last problem can best be fixed by moving the offending documentation back to where it belongs (really, it's not the documentation that is at fault, it's whatever has squeezed in -- the home-breaker -- between the documentation and the thing it was originally attached to). You could use some Doxygen special tags to avoid moving stuff around like that, but it does not help the understandability of the source much.

== Beispiel APIDOX ==

So what does documentation look like in the headers? How do you write a method documenation that describes the parameters as well? This section contains boilerplate for most common situations. Doxygen does not require a strict style -- it will ignore whitespace and asterisks at the beginning of a line, so you can make the documentation ASCII-pretty.

'''Documentation for a file:''' The newline after @file is significant! The text after @author is listed in a special Authors section of the apidox; you can list multiple authors.

<code cppqt>
/** @file
* This file is part of AnApplication and defines
* classes Ungulate and Moose.
*
* @author Mostly by me
*/
</code>

'''Documentation for a namespace:'''

<code cppqt>
/**
* This namespace collects functions related to
* counting and enumeration of mammals and their limbs.
*/
</code>

'''Documentation for a class:''' Some Doxygen special commands are used here to provide additional information. @author (as with files) identifies authors of the code; these are collected in a special ''Authors:'' section of the apidox. You can list more than one author. The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.

<code cppqt>
/**
* This class represents a Moose in the woodland
* simulator. A single Moose object can be created,
* but it is more useful to instantiate Moose::Factory
* by calling Moose::factory(), and then calling spawn()
* for each new Moose, since that maintains the ecological
* balance far better.
*
* @author Adriaan de Groot <degroot@kde.org>
* @since 3.5
*/
</code>

'''Method documentation:''' We can use @author and @since just like we do for classes. In addition, there are the parameters of the method that can be described. @p is used to refer to them in running text, and @param is used to construct a list of parameter descriptions that is specially formatted. Finally, @return entries describe the values that may be returned by the method.

<code cppqt>
/**
* This method names a particular Moose and as a side effect
* sets whether or not the Moose is treated as a Reindeer.
* When @p santa is @c true, the name of the moose is set to
* the next of the available Reindeer (if possible).
*
* @param name name to assign to the Moose, which is only
* relevant if the moose is not a Reindeer.
* @param santa is this Moose assigned to Santa? if so, the
* name is irrelevant.
*
* @return @c true if naming the Moose succeeded
* @return @c false if naming the Moose failed. This only
* happens if the Moose is assigned to Santa duty
* but there are already eight named Reindeer.
*/
bool name(const QString &name, bool santa = false);
</code>

Enum documentation is described in the section on writing new apidox. The same kind of documentation as for classes applies, with the addition of the documentation for each enumerated value which belongs inline.

== Beliebte Fehler ==

This section lists common pitfalls in writing apidox. Typically, they are easily
overlooked mistakes that produce weird error messages, but I will also include
some stylistic pitfalls that should be avoided.

'''Missing APIDOX''': You ''know'' you wrote dox for class Moose, but after
generation they are not visible. You ''know'' that the file-scope function int
foo() is documented, but it's not there either! What is going on?

The most common pitfall, the one that leads to "missing" apidox, is forgetting
to document surrounding structure. The "structure" in the source comes from
files, namespaces, classes and methods. In order to document a class you must
document the namespace it is in (if there is one) and the file that it is in.
In order to document a method, you must document the class it is in (and thus
the namespace and file). So the easiest rule of thumb is to
document ''everything''.
{{note (de)|This hard-and-fast rule is not quite accurate:
classes do not need the file to be documented,
so you can leave out the /** @file */ comment for
source files containing only classes (and namespaces).
Note that classes in a namespace require the namespace
to be documented, but classes in the :: namespace
don't need extra documentation.
I'm not sure about anonymous namespaces.

For file-scoped functions -- that is, functions
that are defined in a file, not in a namespace
and not in a class,
you ''must'' document the file
they are in. This applies mostly
to files which collect a bunch of non-method utility functions.}}

'''Broken parameter documentation:''' Documenting parameters to methods can be done two ways: you can document none of them, or you can document
''all'' of them for a given method. There is no middle ground (that doesn't
generate gobs of errors that you should fix).

If you document ''all'' of your parameters (which is a good thing to do,
and generates things in a nicely formatted fashion), then your method
apidox consists first of a general description of the method and then a
bunch of @param tags which describe each individual parameter. The @param
tag is followed by the name of the parameter -- watch out for spelling
and case-sensitivity! -- and then the description. The description can
span multiple lines.
<code cppqt>
/** Calculate the root-mean-square distance from the
* origin to the given integral coordinate.
*
* @param y y-coordinate, which is on an axis perpendicular to the
* x-axis, yet still in the same plane.
* @param x x-coordinate
*/
</code>

When you document all the parameters like this, Doxygen will complain if
you misspell parameter names, or forget some, or mention parameters that
are not there. This will force you to update the documentation if you
change the method signature. And that's a good thing.

Additional pitfalls are putting the type of the parameter in the list,
like @param int x, which makes "int" the name of the parameter. Another
pitfall is that @param should come after the general description.
Once the @param list starts, nothing can stop it except for other
list-style Doxygen tags like @since, @author or @return. So write @param
after the story and before, say, @return.

If you document ''none'' of the parameters, you do not use the @param tag
at all. You can talk about your parameters by writing @p before the name
of a parameter (or anything else, really, but it only makes sense in front
of a name of a parameter). Like this:
<code cppqt>
/** Calculate the root-mean-square distance from the origin to
* the given integral coordinate which is given as a pair @p x,
* @p y. If @p nonFree is true, use ESR instead of RMS in the
* computation.
*/
double distance(int x, int y, bool nonFree=false);
</code>

'''Misuse of tags in running text:''' This boils down to the warning
above about where to put @param: not every Doxygen tag can go anywhere.
Some start lists or basically end the general description part of a
description, so you need to avoid using them in running text.

'''Chosing between Doxygen errors and compiler warnings:''' If you are
going to document your parameters, you need to name them. If you are
defining a stub method, this can lead to compiler warnings.

'''Accidental tags:''' It can be easy to accidentally use Doxygen tags
in running text -- email addresses, backslash escapes, those are the
easy ones. Watch the Doxygen logs and escape that at sign with a backslash
when needed (i.e. write \@ to get an at sign). It's probably a good
idea to avoid the backslash style of apidox entirely; at the same time, if
you happen to write \moose, Doxygen will complain that that is an invalid
tag.

'''Accidental HTML:''' If you use < and > in your apidox, these may
confuse Doxygen -- especially if you write things like <service>
which look like HTML tags. This is a common way of writing some kind of
element that may be replaced in a method call or string or something, so
it crops up all the time. You know, you write some thing like this:
<code cppqt>
/** This method connects to a database. The connection string is
* composed of a username, password, host and database name as
* follows:
* <username>:<password>@<host>//<database>
*
* @return true if the connection succeeded.
*/
</code>

This bit of dox is terribly broken, because the whole sample connection
string will be interpreted as (bad) HTML and ignored. There are two
solutions:
<ol>
*Write \< instead of just < to escape the < and make Doxygen output it normally. Doxygen is smart enough to turn this into &lt; in HTML output. This has only a minimal impact on readability of the dox in the header files themselves.
*Use the HTML formatting that Doxygen makes available, and write ''foo'' instead of <foo>. This produces nicer output with italics instead of plain text, so it is easier to spot what is the replaceable part of the text. The downside is that it has a larger visible impact on the apidox in the headers.
</ol>

;Superfluous @ref
:It can be tempting -- certainly if you've written dox for other projects -- to use #method or @ref method to force a reference to another method somewhere. Relax, it's not needed and usually causes Doxygen warnings to boot. Just name the method normally, make apidox and watch the references appear naturally.

== KDE spezifische Tags ==
'''@bc''': This tag indicated binary compatibility, much like ''@since'' does. The argument after ''@bc'' is the scope of binary compatibility (for instance, KDE4). Classes that are not marked with ''@bc'' may, in some modules, be flagged as incompatible so that they can be avoided.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @bc KDE4.2 Compatibility is expected to break
* with next-generation mooses.
*/
</code>

'''@libs''': Use this tag to indicate what libraries should be linked in for the given class. Although this is usually the name of the directory the class lives in, this is not always the case.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @libs
* @a -lkdeui or use \$(LIB_KDEUI) in the KDE build framework.
*/
</code>

== Code Beispiele in APIDOX ==

It can be useful to put example code in the APIDOX for a class.
Very useful, in fact, for the reader who is wondering
how exactly to use the class in a straightforward way.
Most classes in {{path|kdelibs/kdecore}} have example code.

One way to write example code is to use @code and @endcode around
blocks of example code in the Doxygen comments themselves, like this:
<code cppqt>
/**
* This class represents a Moose.
* The correct way of generating Meese is to use the factory:
*
* @code
* Moose::Factory outlet = Moose::factory();
* Moose *m = outlet.spawn();
* @endcode
*/
</code>

This is how most of the examples in {{path|kdelibs}}
are done, actually. It works reasonably well, you can pare the
example down to something really minimal and leave out all the
boilerplate.

An important drawback of this approach to writing example code is that
the code is never checked to see if it actually works.
The code is also ''so'' terse, usually, that it's hard
to expand into a complete example that actually compiles and runs.

To solve this problem, you can write ''real code'' that
actually compiles (as part of the test suite for the code
that you have anyway) and that illustrates exactly
how to use the class under consideration in an actual program.
Better yet, you do not need to include ''all'' the code
in the APIDOX, just the interesting bits.
The way to do this is to put the code in a file in the
<tt>tests/</tt> subdirectory of your code.
Then use Doxygen's @include tag to include the
code from that file into the API documentation.

{{warning (de)|Benutze nicht @example! Es macht etwas total anderes als was du erwarten könntest (zum Beispiel fügt es keinen Beispiel-Code ein).}}

== Links ==

[http://www.stack.nl/~dimitri/doxygen/commands.html englische Liste der unterstützen Doxygen Tags]
:Hier ist eine Liste von allen verfügbaren Dokumentations-Tags von Doxygen von der offiziellen Seite. Beachte, das diese Seite ein Backslash vor einem Tag benutzt, während diese Seite immer das At-Zeichen benutzt. Beides ist erlaubt, doch in KDE sollte zu Gunsten der Konsistenz das At-Zeichen benutzt werden.

[[Category:Documentation]]

Development/Tutorials/API Documentation (de)

2008-11-01T11:05:02Z

DrSlowDecay: More translation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/API Documentation}}
__TOC__
{{Box|Definition|
'''API (''Application Programming Interface'') Dokumentation''' ist die Dokumentation eines ''Programmes'' und seiner Schnittstellen. Durch Dokumentation wird einem Entwickler, der mit oder an dem Programm arbeitet, erklärt, wie Dinge funktionieren und wie und welche Methoden aufzurufen sind.

API Dokumentation wird machmal auch API Referenz Handbuch (API reference manual) genannt. Es muß nicht ''nur'' ein Referenz Handbuch sein, obwohl es umfangreiches zusätzliches Material, wie Anleitungen, Zeitleisten, etc., enthalten kann. Auf dieser Seite wird alles Material welches die API eines Codes dokumentiert und erklärt "apidox" genannt.

Gute apidox benötigt etwas Mühe zum schreiben -- doch sicherlich weniger Mühe als gute ''Benutzer'' Dokumentation, da du als Entwickler für andere Entwickler schreibst und eklärst wie Code funktioniert und was er tun soll. So dein Publikum ist bereit damit zu arbeiten. Der Vorteil von apidox zeigt sich, wenn jemand anderes (oder sogar du selbst einige Monate später) den Code (wieder)verwenden oder erweitern möchte. Gute apidox bedeutet, dass jemand neues kommen kann, den Code schnell versteht und nützliche Patches erstellen kann. Gerade für Bibliotheken kann apidox es ermöglichen, diese wie eine Black Box zu benutzen (und so sollte es auch sein), da die benötigte Dokumentation vorliegt und die Dokumentation sich nicht in den tiefen des (vielleicht gar nicht vorliegenden) C codes befindet.|100%}}

== Vorwort ==

Mit APIDOX wird es anderen Entwicklern ermöglicht, auf ein Programm zuzugreifen. Sie sind nicht unbedingt notwenig doch sie helfen neuen Leuten, die an dem Programm arebeiten möchten oder den Code ohne große Änderungen wiederverwenden möchten, sicherlich eine Menge.

Ein Blick auf [http://doc.trolltech.com/latest/ die Qt Dokumentation (englisch)] ermöglicht es, einen Eindruck von guter apidox Dokumentation zu bekommen. Dort sieht man eine Stilkonsistenz, die sich durch die gesamte Dokumentation zieht. Dadurch kann man eine Menge über Qt lernen, nur indem man die Dokumentation liest. Es ist nicht notwendig, die Anleitungsprogramme auszuführen oder den Quellcode zu lesen um herauszufinden, was ein Parameter in einer bestimmten Methode einer Bibliothek macht. Es wird alles bereits erläutert.

Apidox zu schreiben besteht aus zwei Teilen. Der erste Teil ist technischer Natur: Man muß den Code verstehen, der dokumentiert werden soll, oder zumindest wissen, was er tun soll und wie er benutzt werden muss. Der andere Teil ist reine Disziplin: apidox ist am nützlichsten, wenn es sorgfältig und ausführlich benutzt wird.

Dieses Dokument versucht den apidox Prozess nicht zu ausführlich werden zu lassen, indem es einige dirkekte Tips gibt, wie man apidox schreibt. Es gibt dann doch die [[Policies/Library Documentation Policy|library apidox policies (englisch)]], die sehr viel strenger sind. Es schadet nicht, auch dort mal einen Blick reinzuwerfen.

== APIDOX Basics ==

APIDOX are processed by the [http://www.doxygen.org Doxygen] documentation tool. This tool reads source code for your application (or library) and produces nicely formatted documentation from it. There is a good [http://www.stack.nl/~dimitri/doxygen/manual.html reference manual] available -- but let's hope to make it unnecessary to read, for basic use anyway.

{{Tip|You don't even need to have Doxygen installed to work on apidox for your application. Every few hours, the [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] compiles apidox for all of the KDE modules we know about. Logfiles are kept and you can see your apidox on the site, or read the error messages and fix those. ...it might not be the fastest way to write and fix apidox, but it gets the job done, and if you spend just an hour at the end of the day writing some apidox, it's sufficiently useful.}}

{{Tip|If you do have Doxygen installed and want to build the apidox, use the kdedoxygen.sh script as described in [[Development/Tools/apidox|apidox]].}}

Basic apidox are fun and simple: you write comments in your code explaining what things are supposed to be for. These comments are nearly indistinguishable from stuff you would be writing in the headers of your code ''anyway'', so that's not hard to do.

APIDOX are written in special comments. These comments start with /** (slash, star, star) -- that's what makes them special. The rest of the content of the comment is just plain text describing a part of your program. The plain text is interpreted by the Doxygen processor, so that you can write accurate descriptions of parameters, return types, and do some basic text markup. But documentation can be very straighforward: just write down what a method does, surrounded by /** and */, like this:

<code cppqt>
/** This method increases the sexyness of Kontact and should as
* such be called whenever possible (i.e. instead of having idle
* time, you might think of calling this method and helping
* Kontact gain even more popularity). You might even insert it
* into your own event loop to ensure it is called as often as
* possible. If these calls decrease the number of new features,
* it's still no problem to call it.
*/
void incSexyness(KInstance *instance);
</code>

For proper apidox, you need to document every "thing" in your program. "Things" here are directories, files, namespaces, classes, methods, enums, and member variables. You can actually leave out files and directories, and concentrate on the latter. Complete apidox looks something like this:

<code cppqt>
/** Namespace for KDE network-related classes */
namespace KDENetwork {
/** Wrapper for a TCP/IP socket */
class Socket {
public:
/** Constructor. Calls listen() on some random high port. */
Socket();
private:
int fd;
};
}
</code>

You can see here that each nesting level of "things" is documented with a comment -- the namespace, the class and the method. Things that are private do not need apidox, but things that are protected do.

It is important to document each level of nesting, because if you leave one level out, Doxygen will ignore the documentation in inner nesting levels, and you will be left wondering where it has gone. For instance, if we leave out the class documentation, then the method documentation for Socket() will vanish as well. This is one of the common pitfalls to writing apidox.

If you just do this -- write an explanation for every part of your program -- then you're already a long way on the road to having complete apidox. Writing all those explanations makes your program more accessible to other developers -- and often shows you where the design or choice of names is sub-optimal. So it's a win for you both ways.

You can consult the list of supported tags for examples of more fancy apidox -- explaining parameters, for instance, and annotating the apidox with credits and examples. It's also worthwhile to take a look at the section on enabling apidox, but it's also fine to divide the work: you write the apidox themselves, and ask me (mailto:groot@kde.org) to enable apidox generation for your module. And I will.

== APIDOX in neuem Code schreiben ==

If you are writing new code and want to write apidox, use KDevelop. Really. Properly configured, it can automatically set up all the skeletons for apidox that you need, and what you do is write the descriptions. No messing with apidox commands.

If you're not in that fortunate position, the following little checklist should get you through the worst of writing apidox.

'''1. Write apidox as you code'''

The discipline it takes to write down the apidox for function foo() now as you are thinking of foo() and what it needs to do more than compensates the effort later where you have to remember what foo() was supposed to do, anyway.

This isn't to say you have to do it this way, but it is convenient. The apidox also document design decisions. They also document what you want a particular piece of code to do, regardless of what it actually does. That makes it possible to independently check that the code does what it's supposed to: because it's written down.

'''2. Document your headers completely'''

The headers are what's most visible to users (in this context, users are developers who are re-using) of your code, and they should be complete. Document each structural bit of the headers as you go along. This means:

*Every file should have a file-level comment. This is suggested in the KDE guidelines anyway -- near the top of your file, write down what the file is for, vaguely what it defines. Wrap this up in a /** @file */ comment and you are set.
*Every namespace should have a comment. A given namespace only needs a comment once in your source tree (or within one bunch of files that generate apidox together), but it can't hurt to repeat the description on each occasion -- just make it brief. These comments are just plain apidox comments wrapped up in /** */ ; there are no special markups needed like the @file for file comments. Do make sure the comment is just before the namespace and doesn't get distanced from the namespace it documents. The following is fine:
<code cppqt>/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */

namespace Ungulate {
</code>
:In the next example, someone has snuck in some extra stuff between the apidox comment and the namespace it is documenting. This may cause Doxygen errors (so then it is easy to spot) or it may cause the namespace documentation to attach to something wildly different (and then it's hard to spot).
<code cppqt>
/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */
class Mammal;
namespace Ungulate {
</code>
:There is not much you can do about this except to be watching when you insert code -- don't separate apidox from the thing they are documenting.
*Every class should have a comment. Classes are the important building blocks of your application or library, so this is one place where writing lots helps. Write down why the class exists. Write down what it is supposed to do. Give an example of how to use it. Explain how not to use it, or what prerequisites it has (for instance, lots of classes need a KInstance object, but don't document that explicitly). The same caveats apply as with namespace apidox: make sure the class follows its apidox immediately.
*Every method should have a comment explaining what it does and what the parameters are for. Method parameters should be documented using @param. Don't rely on the name of the method or the parameters to be fully self-documenting. Besides, writing these things down properly will trigger Doxygen errors if you change them in an incompatible way later -- and that is going to save you lots of time in finding source and binary incompatibilities and explaining to users why their code suddenly doesn't do what they expect (assuming it compiles at all). So good method apidox is an additional insurance against making bad changes. Same caveats apply.
*Every enumeration type should have a comment explaining what the enumeration is for, even if it's just /** Various constants */.
*Every enumeration value should have a comment too, to explain what it represents. Don't rely on the name of the enumeration value being sufficiently expressive. For the purposes of readability, I suggest that you document enumeration values after the value, as opposed to the documentation format for namespaces, classes and methods where you write the documentation in front of the thing you are documenting. The format of the documentation is slightly different. Instead of writing /** Documentation */ in front, you write /**< Documentation afterards */, where the < denotes that the documentation applies to the thing just past. It looks like this:
<code cppqt>
enum State {
none, /**< No bracket seen */
bracket, /**< Found a ( for grouping */
squote, /**< Found a single quote */
dquote /**< Found double quotes */
};
</code>

'''3. Watch this space!'''

Watch the [http://www.englishbreakfastnetwork.org/ English Breakfast Network] for the [http://www.englishbreakfastnetwork.org/apidocs/ results] of your apidox work. Check the log files for errors -- Doxygen can complain quite loudly.

'''4. Write a main page for your application.'''

This is usually done in a separate file {{path|Mainpage.dox}} in the top-level of a library or application. The file's content is just a single apidox comment that starts with /** @mainpage title ; the rest of the file is just a long comment about what the library or application is for.

== APIDOX in altem Code korrigieren ==

Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)

In old apidox, you are more likely to suffer from the following symptoms:

*Missing parameter documentation (because parameters were renamed, or added, or removed, or something).
*Missing method documentation.
*Missing class documentation.
*Documentation that has wandered off on its own and is attached to the wrong thing now.

The first of these can be fixed by correcting the parameter documentation. See the examples section. The next two -- missing documentation that you can see is there in the source files but that does not show up in the generated HTML pages, is usually a matter of missing documentation on surrounding blocks. See the common pitfalls section, and make sure that the surrounding classes, namespaces and files all have documentation.

The last problem can best be fixed by moving the offending documentation back to where it belongs (really, it's not the documentation that is at fault, it's whatever has squeezed in -- the home-breaker -- between the documentation and the thing it was originally attached to). You could use some Doxygen special tags to avoid moving stuff around like that, but it does not help the understandability of the source much.

== Beispiel APIDOX ==

So what does documentation look like in the headers? How do you write a method documenation that describes the parameters as well? This section contains boilerplate for most common situations. Doxygen does not require a strict style -- it will ignore whitespace and asterisks at the beginning of a line, so you can make the documentation ASCII-pretty.

'''Documentation for a file:''' The newline after @file is significant! The text after @author is listed in a special Authors section of the apidox; you can list multiple authors.

<code cppqt>
/** @file
* This file is part of AnApplication and defines
* classes Ungulate and Moose.
*
* @author Mostly by me
*/
</code>

'''Documentation for a namespace:'''

<code cppqt>
/**
* This namespace collects functions related to
* counting and enumeration of mammals and their limbs.
*/
</code>

'''Documentation for a class:''' Some Doxygen special commands are used here to provide additional information. @author (as with files) identifies authors of the code; these are collected in a special ''Authors:'' section of the apidox. You can list more than one author. The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.

<code cppqt>
/**
* This class represents a Moose in the woodland
* simulator. A single Moose object can be created,
* but it is more useful to instantiate Moose::Factory
* by calling Moose::factory(), and then calling spawn()
* for each new Moose, since that maintains the ecological
* balance far better.
*
* @author Adriaan de Groot <degroot@kde.org>
* @since 3.5
*/
</code>

'''Method documentation:''' We can use @author and @since just like we do for classes. In addition, there are the parameters of the method that can be described. @p is used to refer to them in running text, and @param is used to construct a list of parameter descriptions that is specially formatted. Finally, @return entries describe the values that may be returned by the method.

<code cppqt>
/**
* This method names a particular Moose and as a side effect
* sets whether or not the Moose is treated as a Reindeer.
* When @p santa is @c true, the name of the moose is set to
* the next of the available Reindeer (if possible).
*
* @param name name to assign to the Moose, which is only
* relevant if the moose is not a Reindeer.
* @param santa is this Moose assigned to Santa? if so, the
* name is irrelevant.
*
* @return @c true if naming the Moose succeeded
* @return @c false if naming the Moose failed. This only
* happens if the Moose is assigned to Santa duty
* but there are already eight named Reindeer.
*/
bool name(const QString &name, bool santa = false);
</code>

Enum documentation is described in the section on writing new apidox. The same kind of documentation as for classes applies, with the addition of the documentation for each enumerated value which belongs inline.

== Beliebte Fehler ==

This section lists common pitfalls in writing apidox. Typically, they are easily
overlooked mistakes that produce weird error messages, but I will also include
some stylistic pitfalls that should be avoided.

'''Missing APIDOX''': You ''know'' you wrote dox for class Moose, but after
generation they are not visible. You ''know'' that the file-scope function int
foo() is documented, but it's not there either! What is going on?

The most common pitfall, the one that leads to "missing" apidox, is forgetting
to document surrounding structure. The "structure" in the source comes from
files, namespaces, classes and methods. In order to document a class you must
document the namespace it is in (if there is one) and the file that it is in.
In order to document a method, you must document the class it is in (and thus
the namespace and file). So the easiest rule of thumb is to
document ''everything''.
{{note (de)|This hard-and-fast rule is not quite accurate:
classes do not need the file to be documented,
so you can leave out the /** @file */ comment for
source files containing only classes (and namespaces).
Note that classes in a namespace require the namespace
to be documented, but classes in the :: namespace
don't need extra documentation.
I'm not sure about anonymous namespaces.

For file-scoped functions -- that is, functions
that are defined in a file, not in a namespace
and not in a class,
you ''must'' document the file
they are in. This applies mostly
to files which collect a bunch of non-method utility functions.}}

'''Broken parameter documentation:''' Documenting parameters to methods can be done two ways: you can document none of them, or you can document
''all'' of them for a given method. There is no middle ground (that doesn't
generate gobs of errors that you should fix).

If you document ''all'' of your parameters (which is a good thing to do,
and generates things in a nicely formatted fashion), then your method
apidox consists first of a general description of the method and then a
bunch of @param tags which describe each individual parameter. The @param
tag is followed by the name of the parameter -- watch out for spelling
and case-sensitivity! -- and then the description. The description can
span multiple lines.
<code cppqt>
/** Calculate the root-mean-square distance from the
* origin to the given integral coordinate.
*
* @param y y-coordinate, which is on an axis perpendicular to the
* x-axis, yet still in the same plane.
* @param x x-coordinate
*/
</code>

When you document all the parameters like this, Doxygen will complain if
you misspell parameter names, or forget some, or mention parameters that
are not there. This will force you to update the documentation if you
change the method signature. And that's a good thing.

Additional pitfalls are putting the type of the parameter in the list,
like @param int x, which makes "int" the name of the parameter. Another
pitfall is that @param should come after the general description.
Once the @param list starts, nothing can stop it except for other
list-style Doxygen tags like @since, @author or @return. So write @param
after the story and before, say, @return.

If you document ''none'' of the parameters, you do not use the @param tag
at all. You can talk about your parameters by writing @p before the name
of a parameter (or anything else, really, but it only makes sense in front
of a name of a parameter). Like this:
<code cppqt>
/** Calculate the root-mean-square distance from the origin to
* the given integral coordinate which is given as a pair @p x,
* @p y. If @p nonFree is true, use ESR instead of RMS in the
* computation.
*/
double distance(int x, int y, bool nonFree=false);
</code>

'''Misuse of tags in running text:''' This boils down to the warning
above about where to put @param: not every Doxygen tag can go anywhere.
Some start lists or basically end the general description part of a
description, so you need to avoid using them in running text.

'''Chosing between Doxygen errors and compiler warnings:''' If you are
going to document your parameters, you need to name them. If you are
defining a stub method, this can lead to compiler warnings.

'''Accidental tags:''' It can be easy to accidentally use Doxygen tags
in running text -- email addresses, backslash escapes, those are the
easy ones. Watch the Doxygen logs and escape that at sign with a backslash
when needed (i.e. write \@ to get an at sign). It's probably a good
idea to avoid the backslash style of apidox entirely; at the same time, if
you happen to write \moose, Doxygen will complain that that is an invalid
tag.

'''Accidental HTML:''' If you use < and > in your apidox, these may
confuse Doxygen -- especially if you write things like <service>
which look like HTML tags. This is a common way of writing some kind of
element that may be replaced in a method call or string or something, so
it crops up all the time. You know, you write some thing like this:
<code cppqt>
/** This method connects to a database. The connection string is
* composed of a username, password, host and database name as
* follows:
* <username>:<password>@<host>//<database>
*
* @return true if the connection succeeded.
*/
</code>

This bit of dox is terribly broken, because the whole sample connection
string will be interpreted as (bad) HTML and ignored. There are two
solutions:
<ol>
*Write \< instead of just < to escape the < and make Doxygen output it normally. Doxygen is smart enough to turn this into &lt; in HTML output. This has only a minimal impact on readability of the dox in the header files themselves.
*Use the HTML formatting that Doxygen makes available, and write ''foo'' instead of <foo>. This produces nicer output with italics instead of plain text, so it is easier to spot what is the replaceable part of the text. The downside is that it has a larger visible impact on the apidox in the headers.
</ol>

;Superfluous @ref
:It can be tempting -- certainly if you've written dox for other projects -- to use #method or @ref method to force a reference to another method somewhere. Relax, it's not needed and usually causes Doxygen warnings to boot. Just name the method normally, make apidox and watch the references appear naturally.

== KDE spezifische Tags ==
'''@bc''': This tag indicated binary compatibility, much like ''@since'' does. The argument after ''@bc'' is the scope of binary compatibility (for instance, KDE4). Classes that are not marked with ''@bc'' may, in some modules, be flagged as incompatible so that they can be avoided.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @bc KDE4.2 Compatibility is expected to break
* with next-generation mooses.
*/
</code>

'''@libs''': Use this tag to indicate what libraries should be linked in for the given class. Although this is usually the name of the directory the class lives in, this is not always the case.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @libs
* @a -lkdeui or use \$(LIB_KDEUI) in the KDE build framework.
*/
</code>

== Code Beispiele in APIDOX ==

It can be useful to put example code in the APIDOX for a class.
Very useful, in fact, for the reader who is wondering
how exactly to use the class in a straightforward way.
Most classes in {{path|kdelibs/kdecore}} have example code.

One way to write example code is to use @code and @endcode around
blocks of example code in the Doxygen comments themselves, like this:
<code cppqt>
/**
* This class represents a Moose.
* The correct way of generating Meese is to use the factory:
*
* @code
* Moose::Factory outlet = Moose::factory();
* Moose *m = outlet.spawn();
* @endcode
*/
</code>

This is how most of the examples in {{path|kdelibs}}
are done, actually. It works reasonably well, you can pare the
example down to something really minimal and leave out all the
boilerplate.

An important drawback of this approach to writing example code is that
the code is never checked to see if it actually works.
The code is also ''so'' terse, usually, that it's hard
to expand into a complete example that actually compiles and runs.

To solve this problem, you can write ''real code'' that
actually compiles (as part of the test suite for the code
that you have anyway) and that illustrates exactly
how to use the class under consideration in an actual program.
Better yet, you do not need to include ''all'' the code
in the APIDOX, just the interesting bits.
The way to do this is to put the code in a file in the
<tt>tests/</tt> subdirectory of your code.
Then use Doxygen's @include tag to include the
code from that file into the API documentation.

{{warning (de)|Benutze nicht @example! Es macht etwas total anderes als was du erwarten könntest (zum Beispiel fügt es keinen Beispiel-Code ein).}}

== Links ==

[http://www.stack.nl/~dimitri/doxygen/commands.html englische Liste der unterstützen Doxygen Tags]
:Hier ist eine Liste von allen verfügbaren Dokumentations-Tags von Doxygen von der offiziellen Seite. Beachte, das diese Seite ein Backslash vor einem Tag benutzt, während diese Seite immer das At-Zeichen benutzt. Beides ist erlaubt, doch in KDE sollte zu Gunsten der Konsistenz das At-Zeichen benutzt werden.

[[Category:Documentation]]

Development/Tutorials/API Documentation (de)

2008-11-01T10:48:12Z

DrSlowDecay: /* Vorwort */ translated

{{Template:I18n/Language Navigation Bar|Development/Tutorials/API Documentation}}
__TOC__
{{Box|Definition|
'''API (''Application Programming Interface'') documentation''' is documentation that applies to ''a program'' and its interfaces. It is documentation that explains to a developer who is going to work with the program, or a developer who is going to work on a program, how things work and what methods are there to call.

API documentation is sometimes called an API reference manual. It needn't ''just'' be a reference manual, though, there can be extensive additional material, like tutorials, histories, etc. In this page, we will refer to all the material that documents and explains the API of a piece of code as "apidox."

Good apidox take some effort to write -- but I would say less than good ''user'' documentation, since you as a developer are writing for another developer, and explaining how code works and what it is supposed to do. So your audience is clear to start with. The benefits of apidox come when someone else (or maybe even you several months later) needs to (re)use the code, or extend it. Good apidox means that someone new can show up, understand your code, and produce meaningful patches (that is, ''help'') all the more quickly. Especially for libraries, good apidox make the library usable as a black box (and that's how they should be) because all the needed documentation is available in the apidox and not hidden in the (perhaps inaccessible) C code.|100%}}

== Vorwort ==

Mit APIDOX wird es anderen Entwicklern ermöglicht, auf ein Programm zuzugreifen. Sie sind nicht unbedingt notwenig doch sie helfen neuen Leuten, die an dem Programm arebeiten möchten oder den Code ohne große Änderungen wiederverwenden möchten, sicherlich eine Menge.

Ein Blick auf [http://doc.trolltech.com/latest/ die Qt Dokumentation (englisch)] ermöglicht es, einen Eindruck von guter apidox Dokumentation zu bekommen. Dort sieht man eine Stilkonsistenz, die sich durch die gesamte Dokumentation zieht. Dadurch kann man eine Menge über Qt lernen, nur indem man die Dokumentation liest. Es ist nicht notwendig, die Anleitungsprogramme auszuführen oder den Quellcode zu lesen um herauszufinden, was ein Parameter in einer bestimmten Methode einer Bibliothek macht. Es wird alles bereits erläutert.

Apidox zu schreiben besteht aus zwei Teilen. Der erste Teil ist technischer Natur: Man muß den Code verstehen, der dokumentiert werden soll, oder zumindest wissen, was er tun soll und wie er benutzt werden muss. Der andere Teil ist reine Disziplin: apidox ist am nützlichsten, wenn es sorgfältig und ausführlich benutzt wird.

Dieses Dokument versucht den apidox Prozess nicht zu ausführlich werden zu lassen, indem es einige dirkekte Tips gibt, wie man apidox schreibt. Es gibt dann doch die [[Policies/Library Documentation Policy|library apidox policies (englisch)]], die sehr viel strenger sind. Es schadet nicht, auch dort mal einen Blick reinzuwerfen.

== APIDOX Basics ==

APIDOX are processed by the [http://www.doxygen.org Doxygen] documentation tool. This tool reads source code for your application (or library) and produces nicely formatted documentation from it. There is a good [http://www.stack.nl/~dimitri/doxygen/manual.html reference manual] available -- but let's hope to make it unnecessary to read, for basic use anyway.

{{Tip|You don't even need to have Doxygen installed to work on apidox for your application. Every few hours, the [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] compiles apidox for all of the KDE modules we know about. Logfiles are kept and you can see your apidox on the site, or read the error messages and fix those. ...it might not be the fastest way to write and fix apidox, but it gets the job done, and if you spend just an hour at the end of the day writing some apidox, it's sufficiently useful.}}

{{Tip|If you do have Doxygen installed and want to build the apidox, use the kdedoxygen.sh script as described in [[Development/Tools/apidox|apidox]].}}

Basic apidox are fun and simple: you write comments in your code explaining what things are supposed to be for. These comments are nearly indistinguishable from stuff you would be writing in the headers of your code ''anyway'', so that's not hard to do.

APIDOX are written in special comments. These comments start with /** (slash, star, star) -- that's what makes them special. The rest of the content of the comment is just plain text describing a part of your program. The plain text is interpreted by the Doxygen processor, so that you can write accurate descriptions of parameters, return types, and do some basic text markup. But documentation can be very straighforward: just write down what a method does, surrounded by /** and */, like this:

<code cppqt>
/** This method increases the sexyness of Kontact and should as
* such be called whenever possible (i.e. instead of having idle
* time, you might think of calling this method and helping
* Kontact gain even more popularity). You might even insert it
* into your own event loop to ensure it is called as often as
* possible. If these calls decrease the number of new features,
* it's still no problem to call it.
*/
void incSexyness(KInstance *instance);
</code>

For proper apidox, you need to document every "thing" in your program. "Things" here are directories, files, namespaces, classes, methods, enums, and member variables. You can actually leave out files and directories, and concentrate on the latter. Complete apidox looks something like this:

<code cppqt>
/** Namespace for KDE network-related classes */
namespace KDENetwork {
/** Wrapper for a TCP/IP socket */
class Socket {
public:
/** Constructor. Calls listen() on some random high port. */
Socket();
private:
int fd;
};
}
</code>

You can see here that each nesting level of "things" is documented with a comment -- the namespace, the class and the method. Things that are private do not need apidox, but things that are protected do.

It is important to document each level of nesting, because if you leave one level out, Doxygen will ignore the documentation in inner nesting levels, and you will be left wondering where it has gone. For instance, if we leave out the class documentation, then the method documentation for Socket() will vanish as well. This is one of the common pitfalls to writing apidox.

If you just do this -- write an explanation for every part of your program -- then you're already a long way on the road to having complete apidox. Writing all those explanations makes your program more accessible to other developers -- and often shows you where the design or choice of names is sub-optimal. So it's a win for you both ways.

You can consult the list of supported tags for examples of more fancy apidox -- explaining parameters, for instance, and annotating the apidox with credits and examples. It's also worthwhile to take a look at the section on enabling apidox, but it's also fine to divide the work: you write the apidox themselves, and ask me (mailto:groot@kde.org) to enable apidox generation for your module. And I will.

== APIDOX in neuem Code schreiben ==

If you are writing new code and want to write apidox, use KDevelop. Really. Properly configured, it can automatically set up all the skeletons for apidox that you need, and what you do is write the descriptions. No messing with apidox commands.

If you're not in that fortunate position, the following little checklist should get you through the worst of writing apidox.

'''1. Write apidox as you code'''

The discipline it takes to write down the apidox for function foo() now as you are thinking of foo() and what it needs to do more than compensates the effort later where you have to remember what foo() was supposed to do, anyway.

This isn't to say you have to do it this way, but it is convenient. The apidox also document design decisions. They also document what you want a particular piece of code to do, regardless of what it actually does. That makes it possible to independently check that the code does what it's supposed to: because it's written down.

'''2. Document your headers completely'''

The headers are what's most visible to users (in this context, users are developers who are re-using) of your code, and they should be complete. Document each structural bit of the headers as you go along. This means:

*Every file should have a file-level comment. This is suggested in the KDE guidelines anyway -- near the top of your file, write down what the file is for, vaguely what it defines. Wrap this up in a /** @file */ comment and you are set.
*Every namespace should have a comment. A given namespace only needs a comment once in your source tree (or within one bunch of files that generate apidox together), but it can't hurt to repeat the description on each occasion -- just make it brief. These comments are just plain apidox comments wrapped up in /** */ ; there are no special markups needed like the @file for file comments. Do make sure the comment is just before the namespace and doesn't get distanced from the namespace it documents. The following is fine:
<code cppqt>/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */

namespace Ungulate {
</code>
:In the next example, someone has snuck in some extra stuff between the apidox comment and the namespace it is documenting. This may cause Doxygen errors (so then it is easy to spot) or it may cause the namespace documentation to attach to something wildly different (and then it's hard to spot).
<code cppqt>
/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */
class Mammal;
namespace Ungulate {
</code>
:There is not much you can do about this except to be watching when you insert code -- don't separate apidox from the thing they are documenting.
*Every class should have a comment. Classes are the important building blocks of your application or library, so this is one place where writing lots helps. Write down why the class exists. Write down what it is supposed to do. Give an example of how to use it. Explain how not to use it, or what prerequisites it has (for instance, lots of classes need a KInstance object, but don't document that explicitly). The same caveats apply as with namespace apidox: make sure the class follows its apidox immediately.
*Every method should have a comment explaining what it does and what the parameters are for. Method parameters should be documented using @param. Don't rely on the name of the method or the parameters to be fully self-documenting. Besides, writing these things down properly will trigger Doxygen errors if you change them in an incompatible way later -- and that is going to save you lots of time in finding source and binary incompatibilities and explaining to users why their code suddenly doesn't do what they expect (assuming it compiles at all). So good method apidox is an additional insurance against making bad changes. Same caveats apply.
*Every enumeration type should have a comment explaining what the enumeration is for, even if it's just /** Various constants */.
*Every enumeration value should have a comment too, to explain what it represents. Don't rely on the name of the enumeration value being sufficiently expressive. For the purposes of readability, I suggest that you document enumeration values after the value, as opposed to the documentation format for namespaces, classes and methods where you write the documentation in front of the thing you are documenting. The format of the documentation is slightly different. Instead of writing /** Documentation */ in front, you write /**< Documentation afterards */, where the < denotes that the documentation applies to the thing just past. It looks like this:
<code cppqt>
enum State {
none, /**< No bracket seen */
bracket, /**< Found a ( for grouping */
squote, /**< Found a single quote */
dquote /**< Found double quotes */
};
</code>

'''3. Watch this space!'''

Watch the [http://www.englishbreakfastnetwork.org/ English Breakfast Network] for the [http://www.englishbreakfastnetwork.org/apidocs/ results] of your apidox work. Check the log files for errors -- Doxygen can complain quite loudly.

'''4. Write a main page for your application.'''

This is usually done in a separate file {{path|Mainpage.dox}} in the top-level of a library or application. The file's content is just a single apidox comment that starts with /** @mainpage title ; the rest of the file is just a long comment about what the library or application is for.

== APIDOX in altem Code korrigieren ==

Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)

In old apidox, you are more likely to suffer from the following symptoms:

*Missing parameter documentation (because parameters were renamed, or added, or removed, or something).
*Missing method documentation.
*Missing class documentation.
*Documentation that has wandered off on its own and is attached to the wrong thing now.

The first of these can be fixed by correcting the parameter documentation. See the examples section. The next two -- missing documentation that you can see is there in the source files but that does not show up in the generated HTML pages, is usually a matter of missing documentation on surrounding blocks. See the common pitfalls section, and make sure that the surrounding classes, namespaces and files all have documentation.

The last problem can best be fixed by moving the offending documentation back to where it belongs (really, it's not the documentation that is at fault, it's whatever has squeezed in -- the home-breaker -- between the documentation and the thing it was originally attached to). You could use some Doxygen special tags to avoid moving stuff around like that, but it does not help the understandability of the source much.

== Beispiel APIDOX ==

So what does documentation look like in the headers? How do you write a method documenation that describes the parameters as well? This section contains boilerplate for most common situations. Doxygen does not require a strict style -- it will ignore whitespace and asterisks at the beginning of a line, so you can make the documentation ASCII-pretty.

'''Documentation for a file:''' The newline after @file is significant! The text after @author is listed in a special Authors section of the apidox; you can list multiple authors.

<code cppqt>
/** @file
* This file is part of AnApplication and defines
* classes Ungulate and Moose.
*
* @author Mostly by me
*/
</code>

'''Documentation for a namespace:'''

<code cppqt>
/**
* This namespace collects functions related to
* counting and enumeration of mammals and their limbs.
*/
</code>

'''Documentation for a class:''' Some Doxygen special commands are used here to provide additional information. @author (as with files) identifies authors of the code; these are collected in a special ''Authors:'' section of the apidox. You can list more than one author. The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.

<code cppqt>
/**
* This class represents a Moose in the woodland
* simulator. A single Moose object can be created,
* but it is more useful to instantiate Moose::Factory
* by calling Moose::factory(), and then calling spawn()
* for each new Moose, since that maintains the ecological
* balance far better.
*
* @author Adriaan de Groot <degroot@kde.org>
* @since 3.5
*/
</code>

'''Method documentation:''' We can use @author and @since just like we do for classes. In addition, there are the parameters of the method that can be described. @p is used to refer to them in running text, and @param is used to construct a list of parameter descriptions that is specially formatted. Finally, @return entries describe the values that may be returned by the method.

<code cppqt>
/**
* This method names a particular Moose and as a side effect
* sets whether or not the Moose is treated as a Reindeer.
* When @p santa is @c true, the name of the moose is set to
* the next of the available Reindeer (if possible).
*
* @param name name to assign to the Moose, which is only
* relevant if the moose is not a Reindeer.
* @param santa is this Moose assigned to Santa? if so, the
* name is irrelevant.
*
* @return @c true if naming the Moose succeeded
* @return @c false if naming the Moose failed. This only
* happens if the Moose is assigned to Santa duty
* but there are already eight named Reindeer.
*/
bool name(const QString &name, bool santa = false);
</code>

Enum documentation is described in the section on writing new apidox. The same kind of documentation as for classes applies, with the addition of the documentation for each enumerated value which belongs inline.

== Beliebte Fehler ==

This section lists common pitfalls in writing apidox. Typically, they are easily
overlooked mistakes that produce weird error messages, but I will also include
some stylistic pitfalls that should be avoided.

'''Missing APIDOX''': You ''know'' you wrote dox for class Moose, but after
generation they are not visible. You ''know'' that the file-scope function int
foo() is documented, but it's not there either! What is going on?

The most common pitfall, the one that leads to "missing" apidox, is forgetting
to document surrounding structure. The "structure" in the source comes from
files, namespaces, classes and methods. In order to document a class you must
document the namespace it is in (if there is one) and the file that it is in.
In order to document a method, you must document the class it is in (and thus
the namespace and file). So the easiest rule of thumb is to
document ''everything''.
{{note (de)|This hard-and-fast rule is not quite accurate:
classes do not need the file to be documented,
so you can leave out the /** @file */ comment for
source files containing only classes (and namespaces).
Note that classes in a namespace require the namespace
to be documented, but classes in the :: namespace
don't need extra documentation.
I'm not sure about anonymous namespaces.

For file-scoped functions -- that is, functions
that are defined in a file, not in a namespace
and not in a class,
you ''must'' document the file
they are in. This applies mostly
to files which collect a bunch of non-method utility functions.}}

'''Broken parameter documentation:''' Documenting parameters to methods can be done two ways: you can document none of them, or you can document
''all'' of them for a given method. There is no middle ground (that doesn't
generate gobs of errors that you should fix).

If you document ''all'' of your parameters (which is a good thing to do,
and generates things in a nicely formatted fashion), then your method
apidox consists first of a general description of the method and then a
bunch of @param tags which describe each individual parameter. The @param
tag is followed by the name of the parameter -- watch out for spelling
and case-sensitivity! -- and then the description. The description can
span multiple lines.
<code cppqt>
/** Calculate the root-mean-square distance from the
* origin to the given integral coordinate.
*
* @param y y-coordinate, which is on an axis perpendicular to the
* x-axis, yet still in the same plane.
* @param x x-coordinate
*/
</code>

When you document all the parameters like this, Doxygen will complain if
you misspell parameter names, or forget some, or mention parameters that
are not there. This will force you to update the documentation if you
change the method signature. And that's a good thing.

Additional pitfalls are putting the type of the parameter in the list,
like @param int x, which makes "int" the name of the parameter. Another
pitfall is that @param should come after the general description.
Once the @param list starts, nothing can stop it except for other
list-style Doxygen tags like @since, @author or @return. So write @param
after the story and before, say, @return.

If you document ''none'' of the parameters, you do not use the @param tag
at all. You can talk about your parameters by writing @p before the name
of a parameter (or anything else, really, but it only makes sense in front
of a name of a parameter). Like this:
<code cppqt>
/** Calculate the root-mean-square distance from the origin to
* the given integral coordinate which is given as a pair @p x,
* @p y. If @p nonFree is true, use ESR instead of RMS in the
* computation.
*/
double distance(int x, int y, bool nonFree=false);
</code>

'''Misuse of tags in running text:''' This boils down to the warning
above about where to put @param: not every Doxygen tag can go anywhere.
Some start lists or basically end the general description part of a
description, so you need to avoid using them in running text.

'''Chosing between Doxygen errors and compiler warnings:''' If you are
going to document your parameters, you need to name them. If you are
defining a stub method, this can lead to compiler warnings.

'''Accidental tags:''' It can be easy to accidentally use Doxygen tags
in running text -- email addresses, backslash escapes, those are the
easy ones. Watch the Doxygen logs and escape that at sign with a backslash
when needed (i.e. write \@ to get an at sign). It's probably a good
idea to avoid the backslash style of apidox entirely; at the same time, if
you happen to write \moose, Doxygen will complain that that is an invalid
tag.

'''Accidental HTML:''' If you use < and > in your apidox, these may
confuse Doxygen -- especially if you write things like <service>
which look like HTML tags. This is a common way of writing some kind of
element that may be replaced in a method call or string or something, so
it crops up all the time. You know, you write some thing like this:
<code cppqt>
/** This method connects to a database. The connection string is
* composed of a username, password, host and database name as
* follows:
* <username>:<password>@<host>//<database>
*
* @return true if the connection succeeded.
*/
</code>

This bit of dox is terribly broken, because the whole sample connection
string will be interpreted as (bad) HTML and ignored. There are two
solutions:
<ol>
*Write \< instead of just < to escape the < and make Doxygen output it normally. Doxygen is smart enough to turn this into &lt; in HTML output. This has only a minimal impact on readability of the dox in the header files themselves.
*Use the HTML formatting that Doxygen makes available, and write ''foo'' instead of <foo>. This produces nicer output with italics instead of plain text, so it is easier to spot what is the replaceable part of the text. The downside is that it has a larger visible impact on the apidox in the headers.
</ol>

;Superfluous @ref
:It can be tempting -- certainly if you've written dox for other projects -- to use #method or @ref method to force a reference to another method somewhere. Relax, it's not needed and usually causes Doxygen warnings to boot. Just name the method normally, make apidox and watch the references appear naturally.

== KDE spezifische Tags ==
'''@bc''': This tag indicated binary compatibility, much like ''@since'' does. The argument after ''@bc'' is the scope of binary compatibility (for instance, KDE4). Classes that are not marked with ''@bc'' may, in some modules, be flagged as incompatible so that they can be avoided.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @bc KDE4.2 Compatibility is expected to break
* with next-generation mooses.
*/
</code>

'''@libs''': Use this tag to indicate what libraries should be linked in for the given class. Although this is usually the name of the directory the class lives in, this is not always the case.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @libs
* @a -lkdeui or use \$(LIB_KDEUI) in the KDE build framework.
*/
</code>

== Code Beispiele in APIDOX ==

It can be useful to put example code in the APIDOX for a class.
Very useful, in fact, for the reader who is wondering
how exactly to use the class in a straightforward way.
Most classes in {{path|kdelibs/kdecore}} have example code.

One way to write example code is to use @code and @endcode around
blocks of example code in the Doxygen comments themselves, like this:
<code cppqt>
/**
* This class represents a Moose.
* The correct way of generating Meese is to use the factory:
*
* @code
* Moose::Factory outlet = Moose::factory();
* Moose *m = outlet.spawn();
* @endcode
*/
</code>

This is how most of the examples in {{path|kdelibs}}
are done, actually. It works reasonably well, you can pare the
example down to something really minimal and leave out all the
boilerplate.

An important drawback of this approach to writing example code is that
the code is never checked to see if it actually works.
The code is also ''so'' terse, usually, that it's hard
to expand into a complete example that actually compiles and runs.

To solve this problem, you can write ''real code'' that
actually compiles (as part of the test suite for the code
that you have anyway) and that illustrates exactly
how to use the class under consideration in an actual program.
Better yet, you do not need to include ''all'' the code
in the APIDOX, just the interesting bits.
The way to do this is to put the code in a file in the
<tt>tests/</tt> subdirectory of your code.
Then use Doxygen's @include tag to include the
code from that file into the API documentation.

{{warning (de)|Benutze nicht @example! Es macht etwas total anderes als was du erwarten könntest (zum Beispiel fügt es keinen Beispiel-Code ein).}}

== Links ==

[http://www.stack.nl/~dimitri/doxygen/commands.html englische Liste der unterstützen Doxygen Tags]
:Hier ist eine Liste von allen verfügbaren Dokumentations-Tags von Doxygen von der offiziellen Seite. Beachte, das diese Seite ein Backslash vor einem Tag benutzt, während diese Seite immer das At-Zeichen benutzt. Beides ist erlaubt, doch in KDE sollte zu Gunsten der Konsistenz das At-Zeichen benutzt werden.

[[Category:Documentation]]

Development/Tutorials/API Documentation (de)

2008-11-01T10:31:59Z

DrSlowDecay: Page created and first little translations

{{Template:I18n/Language Navigation Bar|Development/Tutorials/API Documentation}}
__TOC__
{{Box|Definition|
'''API (''Application Programming Interface'') documentation''' is documentation that applies to ''a program'' and its interfaces. It is documentation that explains to a developer who is going to work with the program, or a developer who is going to work on a program, how things work and what methods are there to call.

API documentation is sometimes called an API reference manual. It needn't ''just'' be a reference manual, though, there can be extensive additional material, like tutorials, histories, etc. In this page, we will refer to all the material that documents and explains the API of a piece of code as "apidox."

Good apidox take some effort to write -- but I would say less than good ''user'' documentation, since you as a developer are writing for another developer, and explaining how code works and what it is supposed to do. So your audience is clear to start with. The benefits of apidox come when someone else (or maybe even you several months later) needs to (re)use the code, or extend it. Good apidox means that someone new can show up, understand your code, and produce meaningful patches (that is, ''help'') all the more quickly. Especially for libraries, good apidox make the library usable as a black box (and that's how they should be) because all the needed documentation is available in the apidox and not hidden in the (perhaps inaccessible) C code.|100%}}

== Vorwort ==

APIDOX are what make a program accessible to other contributors. They are not essential, but they certainly help a great deal for new people who want to work on your code, or better yet, re-use it elsewhere with a minimum of modification.

Look at the [http://doc.trolltech.com/latest/ Qt documentation] to get a feeling of what good apidox look like. There is a consistency of style, a thoroughness which permeates all the documentation. It is possible to learn a lot about Qt just from reading the documentation. You do not necessarily need to run the tutorial programs or read the source code of the library to find out what a parameter flags does in some method of the library. It is all spelled out for you.

Writing apidox is a two-part process. One part is technical: you need to understand the code you are documenting -- or at least know what it is supposed to do and how it is meant to be used. The other part is plain discipline: apidox are most useful when they are exhaustive.

This document is going to try to prevent the apidox process from becoming exhausting, by giving straightforward tips about how to write apidox. There are also the [[Policies/Library Documentation Policy|library apidox policies]], which are much stricter, which provide measurable properties that apidox must adhere to. It does not hurt to glance at them now.

== APIDOX Basics ==

APIDOX are processed by the [http://www.doxygen.org Doxygen] documentation tool. This tool reads source code for your application (or library) and produces nicely formatted documentation from it. There is a good [http://www.stack.nl/~dimitri/doxygen/manual.html reference manual] available -- but let's hope to make it unnecessary to read, for basic use anyway.

{{Tip|You don't even need to have Doxygen installed to work on apidox for your application. Every few hours, the [http://www.englishbreakfastnetwork.org/ EnglishBreakfastNetwork] compiles apidox for all of the KDE modules we know about. Logfiles are kept and you can see your apidox on the site, or read the error messages and fix those. ...it might not be the fastest way to write and fix apidox, but it gets the job done, and if you spend just an hour at the end of the day writing some apidox, it's sufficiently useful.}}

{{Tip|If you do have Doxygen installed and want to build the apidox, use the kdedoxygen.sh script as described in [[Development/Tools/apidox|apidox]].}}

Basic apidox are fun and simple: you write comments in your code explaining what things are supposed to be for. These comments are nearly indistinguishable from stuff you would be writing in the headers of your code ''anyway'', so that's not hard to do.

APIDOX are written in special comments. These comments start with /** (slash, star, star) -- that's what makes them special. The rest of the content of the comment is just plain text describing a part of your program. The plain text is interpreted by the Doxygen processor, so that you can write accurate descriptions of parameters, return types, and do some basic text markup. But documentation can be very straighforward: just write down what a method does, surrounded by /** and */, like this:

<code cppqt>
/** This method increases the sexyness of Kontact and should as
* such be called whenever possible (i.e. instead of having idle
* time, you might think of calling this method and helping
* Kontact gain even more popularity). You might even insert it
* into your own event loop to ensure it is called as often as
* possible. If these calls decrease the number of new features,
* it's still no problem to call it.
*/
void incSexyness(KInstance *instance);
</code>

For proper apidox, you need to document every "thing" in your program. "Things" here are directories, files, namespaces, classes, methods, enums, and member variables. You can actually leave out files and directories, and concentrate on the latter. Complete apidox looks something like this:

<code cppqt>
/** Namespace for KDE network-related classes */
namespace KDENetwork {
/** Wrapper for a TCP/IP socket */
class Socket {
public:
/** Constructor. Calls listen() on some random high port. */
Socket();
private:
int fd;
};
}
</code>

You can see here that each nesting level of "things" is documented with a comment -- the namespace, the class and the method. Things that are private do not need apidox, but things that are protected do.

It is important to document each level of nesting, because if you leave one level out, Doxygen will ignore the documentation in inner nesting levels, and you will be left wondering where it has gone. For instance, if we leave out the class documentation, then the method documentation for Socket() will vanish as well. This is one of the common pitfalls to writing apidox.

If you just do this -- write an explanation for every part of your program -- then you're already a long way on the road to having complete apidox. Writing all those explanations makes your program more accessible to other developers -- and often shows you where the design or choice of names is sub-optimal. So it's a win for you both ways.

You can consult the list of supported tags for examples of more fancy apidox -- explaining parameters, for instance, and annotating the apidox with credits and examples. It's also worthwhile to take a look at the section on enabling apidox, but it's also fine to divide the work: you write the apidox themselves, and ask me (mailto:groot@kde.org) to enable apidox generation for your module. And I will.

== APIDOX in neuem Code schreiben ==

If you are writing new code and want to write apidox, use KDevelop. Really. Properly configured, it can automatically set up all the skeletons for apidox that you need, and what you do is write the descriptions. No messing with apidox commands.

If you're not in that fortunate position, the following little checklist should get you through the worst of writing apidox.

'''1. Write apidox as you code'''

The discipline it takes to write down the apidox for function foo() now as you are thinking of foo() and what it needs to do more than compensates the effort later where you have to remember what foo() was supposed to do, anyway.

This isn't to say you have to do it this way, but it is convenient. The apidox also document design decisions. They also document what you want a particular piece of code to do, regardless of what it actually does. That makes it possible to independently check that the code does what it's supposed to: because it's written down.

'''2. Document your headers completely'''

The headers are what's most visible to users (in this context, users are developers who are re-using) of your code, and they should be complete. Document each structural bit of the headers as you go along. This means:

*Every file should have a file-level comment. This is suggested in the KDE guidelines anyway -- near the top of your file, write down what the file is for, vaguely what it defines. Wrap this up in a /** @file */ comment and you are set.
*Every namespace should have a comment. A given namespace only needs a comment once in your source tree (or within one bunch of files that generate apidox together), but it can't hurt to repeat the description on each occasion -- just make it brief. These comments are just plain apidox comments wrapped up in /** */ ; there are no special markups needed like the @file for file comments. Do make sure the comment is just before the namespace and doesn't get distanced from the namespace it documents. The following is fine:
<code cppqt>/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */

namespace Ungulate {
</code>
:In the next example, someone has snuck in some extra stuff between the apidox comment and the namespace it is documenting. This may cause Doxygen errors (so then it is easy to spot) or it may cause the namespace documentation to attach to something wildly different (and then it's hard to spot).
<code cppqt>
/** The Ungulate namespace collects classes and methods
pertaining to hooved animals. */
class Mammal;
namespace Ungulate {
</code>
:There is not much you can do about this except to be watching when you insert code -- don't separate apidox from the thing they are documenting.
*Every class should have a comment. Classes are the important building blocks of your application or library, so this is one place where writing lots helps. Write down why the class exists. Write down what it is supposed to do. Give an example of how to use it. Explain how not to use it, or what prerequisites it has (for instance, lots of classes need a KInstance object, but don't document that explicitly). The same caveats apply as with namespace apidox: make sure the class follows its apidox immediately.
*Every method should have a comment explaining what it does and what the parameters are for. Method parameters should be documented using @param. Don't rely on the name of the method or the parameters to be fully self-documenting. Besides, writing these things down properly will trigger Doxygen errors if you change them in an incompatible way later -- and that is going to save you lots of time in finding source and binary incompatibilities and explaining to users why their code suddenly doesn't do what they expect (assuming it compiles at all). So good method apidox is an additional insurance against making bad changes. Same caveats apply.
*Every enumeration type should have a comment explaining what the enumeration is for, even if it's just /** Various constants */.
*Every enumeration value should have a comment too, to explain what it represents. Don't rely on the name of the enumeration value being sufficiently expressive. For the purposes of readability, I suggest that you document enumeration values after the value, as opposed to the documentation format for namespaces, classes and methods where you write the documentation in front of the thing you are documenting. The format of the documentation is slightly different. Instead of writing /** Documentation */ in front, you write /**< Documentation afterards */, where the < denotes that the documentation applies to the thing just past. It looks like this:
<code cppqt>
enum State {
none, /**< No bracket seen */
bracket, /**< Found a ( for grouping */
squote, /**< Found a single quote */
dquote /**< Found double quotes */
};
</code>

'''3. Watch this space!'''

Watch the [http://www.englishbreakfastnetwork.org/ English Breakfast Network] for the [http://www.englishbreakfastnetwork.org/apidocs/ results] of your apidox work. Check the log files for errors -- Doxygen can complain quite loudly.

'''4. Write a main page for your application.'''

This is usually done in a separate file {{path|Mainpage.dox}} in the top-level of a library or application. The file's content is just a single apidox comment that starts with /** @mainpage title ; the rest of the file is just a long comment about what the library or application is for.

== APIDOX in altem Code korrigieren ==

Writing apidox in old code is a lot like writing the same apidox in new code, except that there is more cruft in the way. The number 1 tip to follow is: watch the logs on English Breakfast Network. Those will show you what errors there are in the apidox. However, Doxygen can't catch everything that is wrong with the documentation on its own, so you will have to do some reading yourself. The other tips for new apidox apply equally here: you want to document everything, in a consistent style. If methods show up on the generated apidox pages with no documentation, you know that you have more apidox to write. (Doxygen may provide an error message, but doesn't do that everywhere in the current setup because there would just be too many.)

In old apidox, you are more likely to suffer from the following symptoms:

*Missing parameter documentation (because parameters were renamed, or added, or removed, or something).
*Missing method documentation.
*Missing class documentation.
*Documentation that has wandered off on its own and is attached to the wrong thing now.

The first of these can be fixed by correcting the parameter documentation. See the examples section. The next two -- missing documentation that you can see is there in the source files but that does not show up in the generated HTML pages, is usually a matter of missing documentation on surrounding blocks. See the common pitfalls section, and make sure that the surrounding classes, namespaces and files all have documentation.

The last problem can best be fixed by moving the offending documentation back to where it belongs (really, it's not the documentation that is at fault, it's whatever has squeezed in -- the home-breaker -- between the documentation and the thing it was originally attached to). You could use some Doxygen special tags to avoid moving stuff around like that, but it does not help the understandability of the source much.

== Beispiel APIDOX ==

So what does documentation look like in the headers? How do you write a method documenation that describes the parameters as well? This section contains boilerplate for most common situations. Doxygen does not require a strict style -- it will ignore whitespace and asterisks at the beginning of a line, so you can make the documentation ASCII-pretty.

'''Documentation for a file:''' The newline after @file is significant! The text after @author is listed in a special Authors section of the apidox; you can list multiple authors.

<code cppqt>
/** @file
* This file is part of AnApplication and defines
* classes Ungulate and Moose.
*
* @author Mostly by me
*/
</code>

'''Documentation for a namespace:'''

<code cppqt>
/**
* This namespace collects functions related to
* counting and enumeration of mammals and their limbs.
*/
</code>

'''Documentation for a class:''' Some Doxygen special commands are used here to provide additional information. @author (as with files) identifies authors of the code; these are collected in a special ''Authors:'' section of the apidox. You can list more than one author. The @since tag tells users since when the class has existed. It is usual to put a KDE release number here.

<code cppqt>
/**
* This class represents a Moose in the woodland
* simulator. A single Moose object can be created,
* but it is more useful to instantiate Moose::Factory
* by calling Moose::factory(), and then calling spawn()
* for each new Moose, since that maintains the ecological
* balance far better.
*
* @author Adriaan de Groot <degroot@kde.org>
* @since 3.5
*/
</code>

'''Method documentation:''' We can use @author and @since just like we do for classes. In addition, there are the parameters of the method that can be described. @p is used to refer to them in running text, and @param is used to construct a list of parameter descriptions that is specially formatted. Finally, @return entries describe the values that may be returned by the method.

<code cppqt>
/**
* This method names a particular Moose and as a side effect
* sets whether or not the Moose is treated as a Reindeer.
* When @p santa is @c true, the name of the moose is set to
* the next of the available Reindeer (if possible).
*
* @param name name to assign to the Moose, which is only
* relevant if the moose is not a Reindeer.
* @param santa is this Moose assigned to Santa? if so, the
* name is irrelevant.
*
* @return @c true if naming the Moose succeeded
* @return @c false if naming the Moose failed. This only
* happens if the Moose is assigned to Santa duty
* but there are already eight named Reindeer.
*/
bool name(const QString &name, bool santa = false);
</code>

Enum documentation is described in the section on writing new apidox. The same kind of documentation as for classes applies, with the addition of the documentation for each enumerated value which belongs inline.

== Beliebte Fehler ==

This section lists common pitfalls in writing apidox. Typically, they are easily
overlooked mistakes that produce weird error messages, but I will also include
some stylistic pitfalls that should be avoided.

'''Missing APIDOX''': You ''know'' you wrote dox for class Moose, but after
generation they are not visible. You ''know'' that the file-scope function int
foo() is documented, but it's not there either! What is going on?

The most common pitfall, the one that leads to "missing" apidox, is forgetting
to document surrounding structure. The "structure" in the source comes from
files, namespaces, classes and methods. In order to document a class you must
document the namespace it is in (if there is one) and the file that it is in.
In order to document a method, you must document the class it is in (and thus
the namespace and file). So the easiest rule of thumb is to
document ''everything''.
{{note (de)|This hard-and-fast rule is not quite accurate:
classes do not need the file to be documented,
so you can leave out the /** @file */ comment for
source files containing only classes (and namespaces).
Note that classes in a namespace require the namespace
to be documented, but classes in the :: namespace
don't need extra documentation.
I'm not sure about anonymous namespaces.

For file-scoped functions -- that is, functions
that are defined in a file, not in a namespace
and not in a class,
you ''must'' document the file
they are in. This applies mostly
to files which collect a bunch of non-method utility functions.}}

'''Broken parameter documentation:''' Documenting parameters to methods can be done two ways: you can document none of them, or you can document
''all'' of them for a given method. There is no middle ground (that doesn't
generate gobs of errors that you should fix).

If you document ''all'' of your parameters (which is a good thing to do,
and generates things in a nicely formatted fashion), then your method
apidox consists first of a general description of the method and then a
bunch of @param tags which describe each individual parameter. The @param
tag is followed by the name of the parameter -- watch out for spelling
and case-sensitivity! -- and then the description. The description can
span multiple lines.
<code cppqt>
/** Calculate the root-mean-square distance from the
* origin to the given integral coordinate.
*
* @param y y-coordinate, which is on an axis perpendicular to the
* x-axis, yet still in the same plane.
* @param x x-coordinate
*/
</code>

When you document all the parameters like this, Doxygen will complain if
you misspell parameter names, or forget some, or mention parameters that
are not there. This will force you to update the documentation if you
change the method signature. And that's a good thing.

Additional pitfalls are putting the type of the parameter in the list,
like @param int x, which makes "int" the name of the parameter. Another
pitfall is that @param should come after the general description.
Once the @param list starts, nothing can stop it except for other
list-style Doxygen tags like @since, @author or @return. So write @param
after the story and before, say, @return.

If you document ''none'' of the parameters, you do not use the @param tag
at all. You can talk about your parameters by writing @p before the name
of a parameter (or anything else, really, but it only makes sense in front
of a name of a parameter). Like this:
<code cppqt>
/** Calculate the root-mean-square distance from the origin to
* the given integral coordinate which is given as a pair @p x,
* @p y. If @p nonFree is true, use ESR instead of RMS in the
* computation.
*/
double distance(int x, int y, bool nonFree=false);
</code>

'''Misuse of tags in running text:''' This boils down to the warning
above about where to put @param: not every Doxygen tag can go anywhere.
Some start lists or basically end the general description part of a
description, so you need to avoid using them in running text.

'''Chosing between Doxygen errors and compiler warnings:''' If you are
going to document your parameters, you need to name them. If you are
defining a stub method, this can lead to compiler warnings.

'''Accidental tags:''' It can be easy to accidentally use Doxygen tags
in running text -- email addresses, backslash escapes, those are the
easy ones. Watch the Doxygen logs and escape that at sign with a backslash
when needed (i.e. write \@ to get an at sign). It's probably a good
idea to avoid the backslash style of apidox entirely; at the same time, if
you happen to write \moose, Doxygen will complain that that is an invalid
tag.

'''Accidental HTML:''' If you use < and > in your apidox, these may
confuse Doxygen -- especially if you write things like <service>
which look like HTML tags. This is a common way of writing some kind of
element that may be replaced in a method call or string or something, so
it crops up all the time. You know, you write some thing like this:
<code cppqt>
/** This method connects to a database. The connection string is
* composed of a username, password, host and database name as
* follows:
* <username>:<password>@<host>//<database>
*
* @return true if the connection succeeded.
*/
</code>

This bit of dox is terribly broken, because the whole sample connection
string will be interpreted as (bad) HTML and ignored. There are two
solutions:
<ol>
*Write \< instead of just < to escape the < and make Doxygen output it normally. Doxygen is smart enough to turn this into &lt; in HTML output. This has only a minimal impact on readability of the dox in the header files themselves.
*Use the HTML formatting that Doxygen makes available, and write ''foo'' instead of <foo>. This produces nicer output with italics instead of plain text, so it is easier to spot what is the replaceable part of the text. The downside is that it has a larger visible impact on the apidox in the headers.
</ol>

;Superfluous @ref
:It can be tempting -- certainly if you've written dox for other projects -- to use #method or @ref method to force a reference to another method somewhere. Relax, it's not needed and usually causes Doxygen warnings to boot. Just name the method normally, make apidox and watch the references appear naturally.

== KDE spezifische Tags ==
'''@bc''': This tag indicated binary compatibility, much like ''@since'' does. The argument after ''@bc'' is the scope of binary compatibility (for instance, KDE4). Classes that are not marked with ''@bc'' may, in some modules, be flagged as incompatible so that they can be avoided.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @bc KDE4.2 Compatibility is expected to break
* with next-generation mooses.
*/
</code>

'''@libs''': Use this tag to indicate what libraries should be linked in for the given class. Although this is usually the name of the directory the class lives in, this is not always the case.

Example:
<code cpp>
/**
* This class emulates a Moose.
* @libs
* @a -lkdeui or use \$(LIB_KDEUI) in the KDE build framework.
*/
</code>

== Code Beispiele in APIDOX ==

It can be useful to put example code in the APIDOX for a class.
Very useful, in fact, for the reader who is wondering
how exactly to use the class in a straightforward way.
Most classes in {{path|kdelibs/kdecore}} have example code.

One way to write example code is to use @code and @endcode around
blocks of example code in the Doxygen comments themselves, like this:
<code cppqt>
/**
* This class represents a Moose.
* The correct way of generating Meese is to use the factory:
*
* @code
* Moose::Factory outlet = Moose::factory();
* Moose *m = outlet.spawn();
* @endcode
*/
</code>

This is how most of the examples in {{path|kdelibs}}
are done, actually. It works reasonably well, you can pare the
example down to something really minimal and leave out all the
boilerplate.

An important drawback of this approach to writing example code is that
the code is never checked to see if it actually works.
The code is also ''so'' terse, usually, that it's hard
to expand into a complete example that actually compiles and runs.

To solve this problem, you can write ''real code'' that
actually compiles (as part of the test suite for the code
that you have anyway) and that illustrates exactly
how to use the class under consideration in an actual program.
Better yet, you do not need to include ''all'' the code
in the APIDOX, just the interesting bits.
The way to do this is to put the code in a file in the
<tt>tests/</tt> subdirectory of your code.
Then use Doxygen's @include tag to include the
code from that file into the API documentation.

{{warning (de)|Benutze nicht @example! Es macht etwas total anderes als was du erwarten könntest (zum Beispiel fügt es keinen Beispiel-Code ein).}}

== Links ==

[http://www.stack.nl/~dimitri/doxygen/commands.html englische Liste der unterstützen Doxygen Tags]
:Hier ist eine Liste von allen verfügbaren Dokumentations-Tags von Doxygen von der offiziellen Seite. Beachte, das diese Seite ein Backslash vor einem Tag benutzt, während diese Seite immer das At-Zeichen benutzt. Beides ist erlaubt, doch in KDE sollte zu Gunsten der Konsistenz das At-Zeichen benutzt werden.

[[Category:Documentation]]

Development/Tutorials/Services/Plugins

2008-11-01T10:14:51Z

DrSlowDecay: +language navigation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Services/Plugins}}

{{TutorialBrowser|

series=Services|

name=Creating and Loading Plugins Using KService|

pre=[[../Traders|Traders: Querying the System]]

}}

== Abstract ==
Before starting with the code let's see which advantages we can undertake
developing a plugin structured application. First of all an application capable
of managing plugins can extend its features with apparently no limits. Anyway, rather than developing a plugin structured application because "it's so coool!!" the developer should think about the real advantages of this kind of development. For instance we can think about an archive manager application: the main program can delegate the creation/extraction/editing of each type of archive to specific plugins. This way we give modularity to the application so that supporting brand new archive types in the future will simply consist in writing the specific plugin and not rewriting the whole application. Ok, then let's stop talking.. and start coding =).

== The Text Editor Example ==
So, even if an archiving application would be nicer to look at, here we will examine a simple text editing application capable of plugin loading.
Each plugin will simply give a specific text editing feature.

== Creating a Plugin Interface Class ==
The main step to create a plugin structure is to define its base class.
This class will be inherited by every plugin and shuld give access to the key resources of the main application. In this example the main plugin class will inherit a KXMLGUIClient since every plugin will give access to its features through a gui element (a KAction in this case).

<code cppqt>
#include <kdemacros.h>
#include <kxmlguiclient.h>
#include <QObject>

class KTextEdit;

class KDE_EXPORT Plugin : public QObject , public KXMLGUIClient
{
Q_OBJECT

public:
Plugin(QObject *parent);
virtual ~Plugin();

/**
* @return KTextEdit pointing to the main application editor widget
*/
KTextEdit* editorInterface();

/**
* @internal Used by the main application to correctly set the editor.
* Do not call from within the reimplementation.
*/
void setEditorInterface(KTextEdit *);

private:
class PluginPrivate;
PluginPrivate *d;

};
</code>

== The Plugin Factory Macro ==

== Registering a Plugin Type ==

== Registering a Plugin With the SyCoCa ==

== Finding Plugins ==

== Instantiating Plugins ==

Development/Tutorials/Using KParts (de)

2008-09-23T14:59:42Z

DrSlowDecay: Translated the rest

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KParts}}

{{TutorialBrowser (de)|

series=Plugins und KParts|

name=Wie man KParts benutzt|

pre=[[Development/Tutorials/KCmdLineArgs (de)|Anleitung 5 - Kommandozeilenargumente]]|

reading=[http://api.kde.org/4.x-api/kdelibs-apidocs/kparts/html/index.html KParts Dokumentation (englisch)]
}}

== Einführung ==

Die KPart Technologie wird in KDE benutzt, um GUI Komponenten wiederzuverwerten. Der Vorteile eines KParts sind dabei die vordefinierte Aktionen, wie Werkzeugleistenknöpfe. Indem man kparts in Applikationen benutzt, braucht ein Entwickler weniger Zeit in die Implementation eines Texteditors oder Kommandozeilenaktionen investieren und statt dessen einfach ein katepart oder ein konsolepart benutzen. KParts werden auch mit der Plugin Technologie benutzt, um Applikationen in andere einzubetten, wie es zum Beispiel die PIM Applikationen in Kontact machen.

Diese Anleitung zeigt, wie man ein KPart in der eigenen Applikation einsetzt und wie man sein eigenes KPart erzeugt.

== Katepart benutzen ==

Einfache KDE Applikationen benutzen ein MainWindow welches von KMainWindow abgeleitet wird (so wie in den vorigen Anleitungen). Um ein KPart in einer Applikation verwenden zu können, muß das MainWindows statt dessen von KParts::MainWindow abgeleitet werden. Dadurch wird sichergestellt, dass die Integration von Werkzeugleiste und Menüeintragen und dem KPart vernünftig funktioniert.

Der folgende Code erzeugt ein KParts::MainWindow mit einem kpart darin.

=== main.cpp ===

<code cppqt n>
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>
#include <KUrl>

#include "mainwindow.h"

int main (int argc, char *argv[])
{
KAboutData aboutData( "kparttutorial1", "kparttutorial1",
ki18n("KPart Tutorial 1"), "0.1",
ki18n("A MainWindow for a KatePart."),
KAboutData::License_GPL,
ki18n("Copyright (c) 2007 Developer") );
KCmdLineArgs::init( argc, argv, &aboutData );

KCmdLineOptions options;
options.add("+[file]", ki18n("Document to open"));
KCmdLineArgs::addCmdLineOptions(options);

KApplication app;

MainWindow* window = new MainWindow();
window->show();

KCmdLineArgs *args = KCmdLineArgs::parsedArgs();
if(args->count())
{
window->load(args->url(0).url());
}

return app.exec();
}

</code>

Die main.cpp Datei ist die gleiche die in [[Development/Tutorials/KCmdLineArgs (de)|Anleitung 5 - Kommandozeilenargumente]] benutzt wurde. Der einzige Unterschied liegt in den Details von KAboutData.

=== mainwindow.h ===

<code cppqt n>

#ifndef KPARTTUTORIAL1_H
#define KPARTTUTORIAL1_H

#include <kparts/mainwindow.h>

/**
* This is the application "Shell". It has a menubar, toolbar, and
* statusbar but relies on the "Part" to do all the real work.
*
* @short Application Shell
* @author Developer <developer@kde.org>
* @version 0.1
*/
class MainWindow : public KParts::MainWindow
{
Q_OBJECT
public:
/**
* Default Constructor
*/
MainWindow();

/**
* Default Destructor
*/
virtual ~MainWindow();

/**
* Use this method to load whatever file/URL you have
*/
void load(const KUrl& url);

private:
void setupActions();

private:
KParts::ReadWritePart *m_part;
};

#endif // KPARTTUT1_H

</code>

Die mainwindow.h Datei ist sehr einfach. Das wichtigste darin ist, dass die MainWindo Klasse von KParts::MainWindow abgeleitet wird.

=== mainwindow.cpp ===

<code cppqt n>

#include "mainwindow.h"

#include <kaction.h>
#include <kactioncollection.h>
#include <kconfig.h>
#include <kedittoolbar.h>
#include <kfiledialog.h>
#include <kshortcutsdialog.h>
#include <klibloader.h>
#include <kmessagebox.h>
#include <kstandardaction.h>
#include <kstatusbar.h>
#include <kurl.h>

#include <QApplication>

MainWindow::MainWindow()
: KParts::MainWindow( )
{

// Setup our actions
setupActions();

// this routine will find and load our Part.
KLibFactory *factory = KLibLoader::self()->factory("katepart");
if (factory)
{
// now that the Part is loaded, we cast it to a Part to get
// our hands on it
m_part = static_cast<KParts::ReadWritePart *>
(factory->create(this, "KatePart" ));

if (m_part)
{
// tell the KParts::MainWindow that this is indeed
// the main widget
setCentralWidget(m_part->widget());

setupGUI(ToolBar | Keys | StatusBar | Save);

// and integrate the part's GUI with the shell's
createGUI(m_part);
}
}
else
{
// if we couldn't find our Part, we exit since the Shell by
// itself can't do anything useful
KMessageBox::error(this, "Could not find our Part!");
qApp->quit();
// we return here, cause qApp->quit() only means "exit the
// next time we enter the event loop...
return;
}
}

MainWindow::~MainWindow()
{
}

void MainWindow::load(const KUrl& url)
{
m_part->openUrl( url );
}

void MainWindow::setupActions()
{
KStandardAction::open(this, SLOT(fileOpen()),
actionCollection());
KStandardAction::quit(qApp, SLOT(closeAllWindows()),
actionCollection());
}

void MainWindow::load()
{
load(KFileDialog::getOpenUrl());
}

</code>

Die mainwindow.cpp Datei enthält die Implementation von MainWindow. Der Konstruktor dieser Klasse enthält den gesamten Code um das KPart zu laden.

Als erstes werden hier die Aktionen des Hautfensters (Öffnen und Beenden) aufgesezt, und dann die Gui-Elemente aufgesetzt, die damit arbeiten sollen (Werkzeugleisten, Menüenträge, Tastenkürzel). Als nächstes kommt der Standardcode, um das KPart zu laden. Die createGUI Methode ist verantwortlich dafür, die Werkzeugleisten und Menüs des KParts mit denen der restlichen Applikation zu vermischen.

=== kparttut1ui.rc ===

<code xml n>
<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<kpartgui name="kparttut1" version="1">
<MenuBar>
<Menu noMerge="1" name="file"><text>&File</text>
<Action name="file_open"/>
<Separator/>
<Merge/>
<Separator/>
<Action name="file_quit"/>
</Menu>

<Merge />
</MenuBar>
<ToolBar noMerge="1" name="mainToolBar"><text>Main Toolbar</text>
<Action name="file_open"/>
<Merge/>
</ToolBar>
</kpartgui>
</code>

Die kparttut1ui.rc Datei wird benutzt, um zu definieren, wie die Aktionen im KPart und im Hauptfenster zusammengesmischt werden sollen. Die <tt><Merge /></tt> Elemente im Dateimenü zeigen zum Beispiel an, dass jeder Part, der Aktionen für das Dateimenü liefert, diese nach file_open und vor file_quit einfügen soll.

=== CMakeLists.txt ===

<code ini n>

project(kparttut1)

FIND_PACKAGE(KDE4 REQUIRED)
INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} . )

set(kparttut1_SRCS
main.cpp
mainwindow.cpp
)

kde4_add_executable(kparttut1 ${kparttut1_SRCS})

target_link_libraries(kparttut1 ${KDE4_KDEUI_LIBS} ${KDE4_KPARTS_LIBS})

########### install files ###############
install(TARGETS kparttut1 DESTINATION ${BIN_INSTALL_DIR} )
install( FILES kparttut1ui.rc
DESTINATION ${DATA_INSTALL_DIR}/kparttut1 )
</code>
Die CMakeLists.txt Datei ist in diesem Fall sehr einfach.

== Die Applikation ausführen ==

Nach dem Kompilieren der Appikation kann diese mit
<code bash>
kparttut1 filename
</code>
ausgeführt werden. filename ist dabei eine Textdatei, die geladen werden soll. Eine der Quellcodedateien wäre ein gutes Beispiel dafür.

Wenn die Datei geladen wird, steht einem ein kompletter kate-Editor in seinem eigenen Fenster zu Verfügung. Alle Features des Editors sind über die Werkzeugleiste und Menüs verfügbar.

Weiterhin fällt die 'Öffnen' Aktion auf, welche in der MainWindow class definiert wurde und auch in der Werkzeugleiste und im Menü neben der 'Beenden' Aktion erscheint.

Die nächste Anleitung wird sich mit dem Erzeugen eigener kparts für die Benutzung in anderen Applikationen beschäftigen.

Development/Tutorials/Using KParts (de)

2008-09-23T14:47:10Z

DrSlowDecay: Page created and initial translation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KParts}}

{{TutorialBrowser (de)|

series=Plugins und KParts|

name=Wie man KParts benutzt|

pre=[[Development/Tutorials/KCmdLineArgs (de)|Anleitung 5 - Kommandozeilenargumente]]|

reading=[http://api.kde.org/4.x-api/kdelibs-apidocs/kparts/html/index.html KParts Dokumentation (englisch)]
}}

== Einführung ==

Die KPart Technologie wird in KDE benutzt, um GUI Komponenten wiederzuverwerten. Der Vorteile eines KParts sind dabei die vordefinierte Aktionen, wie Werkzeugleistenknöpfe. Indem man kparts in Applikationen benutzt, braucht ein Entwickler weniger Zeit in die Implementation eines Texteditors oder Kommandozeilenaktionen investieren und statt dessen einfach ein katepart oder ein konsolepart benutzen. KParts werden auch mit der Plugin Technologie benutzt, um Applikationen in andere einzubetten, wie es zum Beispiel die PIM Applikationen in Kontact machen.

Diese Anleitung zeigt, wie man ein KPart in der eigenen Applikation einsetzt und wie man sein eigenes KPart erzeugt.

== Katepart benutzen ==

Simple KDE applications use a MainWindow derived from KMainWindow (such as in previous tutorials). To use a KPart in an application, the MainWindow must instead be derived from KParts::MainWindow. This will then take care of integrating the toolbar and menu items of the kpart together.

The following code creates a KParts::MainWindow with a kpart inside it.

=== main.cpp ===

<code cppqt n>
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>
#include <KUrl>

#include "mainwindow.h"

int main (int argc, char *argv[])
{
KAboutData aboutData( "kparttutorial1", "kparttutorial1",
ki18n("KPart Tutorial 1"), "0.1",
ki18n("A MainWindow for a KatePart."),
KAboutData::License_GPL,
ki18n("Copyright (c) 2007 Developer") );
KCmdLineArgs::init( argc, argv, &aboutData );

KCmdLineOptions options;
options.add("+[file]", ki18n("Document to open"));
KCmdLineArgs::addCmdLineOptions(options);

KApplication app;

MainWindow* window = new MainWindow();
window->show();

KCmdLineArgs *args = KCmdLineArgs::parsedArgs();
if(args->count())
{
window->load(args->url(0).url());
}

return app.exec();
}

</code>

The main.cpp file is the same as that used in [[Development/Tutorials/KCmdLineArgs|Tutorial 5 - Command line arguments]].The only difference is in the details of the KAboutData.

=== mainwindow.h ===

<code cppqt n>

#ifndef KPARTTUTORIAL1_H
#define KPARTTUTORIAL1_H

#include <kparts/mainwindow.h>

/**
* This is the application "Shell". It has a menubar, toolbar, and
* statusbar but relies on the "Part" to do all the real work.
*
* @short Application Shell
* @author Developer <developer@kde.org>
* @version 0.1
*/
class MainWindow : public KParts::MainWindow
{
Q_OBJECT
public:
/**
* Default Constructor
*/
MainWindow();

/**
* Default Destructor
*/
virtual ~MainWindow();

/**
* Use this method to load whatever file/URL you have
*/
void load(const KUrl& url);

private:
void setupActions();

private:
KParts::ReadWritePart *m_part;
};

#endif // KPARTTUT1_H

</code>

The mainwindow.h file is very simple. The important thing to notice here is that the MainWindow class inherits from KParts::MainWindow.

=== mainwindow.cpp ===

<code cppqt n>

#include "mainwindow.h"

#include <kaction.h>
#include <kactioncollection.h>
#include <kconfig.h>
#include <kedittoolbar.h>
#include <kfiledialog.h>
#include <kshortcutsdialog.h>
#include <klibloader.h>
#include <kmessagebox.h>
#include <kstandardaction.h>
#include <kstatusbar.h>
#include <kurl.h>

#include <QApplication>

MainWindow::MainWindow()
: KParts::MainWindow( )
{

// Setup our actions
setupActions();

// this routine will find and load our Part.
KLibFactory *factory = KLibLoader::self()->factory("katepart");
if (factory)
{
// now that the Part is loaded, we cast it to a Part to get
// our hands on it
m_part = static_cast<KParts::ReadWritePart *>
(factory->create(this, "KatePart" ));

if (m_part)
{
// tell the KParts::MainWindow that this is indeed
// the main widget
setCentralWidget(m_part->widget());

setupGUI(ToolBar | Keys | StatusBar | Save);

// and integrate the part's GUI with the shell's
createGUI(m_part);
}
}
else
{
// if we couldn't find our Part, we exit since the Shell by
// itself can't do anything useful
KMessageBox::error(this, "Could not find our Part!");
qApp->quit();
// we return here, cause qApp->quit() only means "exit the
// next time we enter the event loop...
return;
}
}

MainWindow::~MainWindow()
{
}

void MainWindow::load(const KUrl& url)
{
m_part->openUrl( url );
}

void MainWindow::setupActions()
{
KStandardAction::open(this, SLOT(fileOpen()),
actionCollection());
KStandardAction::quit(qApp, SLOT(closeAllWindows()),
actionCollection());
}

void MainWindow::load()
{
load(KFileDialog::getOpenUrl());
}

</code>

The mainwindow.cpp file contains the implementation of MainWindow. The constructor of this class contains all the code used to load the KPart.

First it sets up the actions used by the main window (Open and Quit), and then sets up the gui elements to go with these items (toolbar items, menu items, keyboard shortcuts). Next is the standard code used to load the KPart. The createGUI method is responsible for merging the toolbars and menus of the KPart with the rest of the application.

=== kparttut1ui.rc ===

<code xml n>
<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<kpartgui name="kparttut1" version="1">
<MenuBar>
<Menu noMerge="1" name="file"><text>&File</text>
<Action name="file_open"/>
<Separator/>
<Merge/>
<Separator/>
<Action name="file_quit"/>
</Menu>

<Merge />
</MenuBar>
<ToolBar noMerge="1" name="mainToolBar"><text>Main Toolbar</text>
<Action name="file_open"/>
<Merge/>
</ToolBar>
</kpartgui>
</code>

The kparttut1ui.rc file is used to define how the actions in the part and the actions in the main window will be merged together. The <tt><Merge /></tt> element in the file menu for example indicates that any part containing actions in a file menu should list its parts after the file_open action and before the file_quit action.

=== CMakeLists.txt ===

<code ini n>

project(kparttut1)

FIND_PACKAGE(KDE4 REQUIRED)
INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} . )

set(kparttut1_SRCS
main.cpp
mainwindow.cpp
)

kde4_add_executable(kparttut1 ${kparttut1_SRCS})

target_link_libraries(kparttut1 ${KDE4_KDEUI_LIBS} ${KDE4_KPARTS_LIBS})

########### install files ###############
install(TARGETS kparttut1 DESTINATION ${BIN_INSTALL_DIR} )
install( FILES kparttut1ui.rc
DESTINATION ${DATA_INSTALL_DIR}/kparttut1 )
</code>
Die CMakeLists.txt Datei ist in diesem Fall sehr einfach.

== Die Applikation ausführen ==

Nach dem Kompilieren der Appikation kann diese mit
<code bash>
kparttut1 filename
</code>
ausgeführt werden. filename ist dabei eine Textdatei, die geladen werden soll. Eine der Quellcodedateien wäre ein gutes Beispiel dafür.

Wenn die Datei geladen wird, steht einem ein kompletter kate-Editor in seinem eigenen Fenster zu Verfügung. Alle Features des Editors sind über die Werkzeugleiste und Menüs verfügbar.

Weiterhin fällt die 'Öffnen' Aktion auf, welche in der MainWindow class definiert wurde und auch in der Werkzeugleiste und im Menü neben der 'Beenden' Aktion erscheint.

Die nächste Anleitung wird sich mit dem Erzeugen eigener kparts für die Benutzung in anderen Applikationen beschäftigen.

Getting Started/Sources/Subversion (de)

2008-05-05T18:03:46Z

DrSlowDecay: Even some more translation

{{Template:I18n/Language Navigation Bar|Getting Started/Sources/Using Subversion with KDE}}

{{TutorialBrowser (de)|

series=Anfang|

name=Subversion mit KDE benutzen|
}}

== Zusammenfassung ==

Der folgende Text ist eine schnelle kde-spezifische Einführung, wie man Subversion benutzt, um auf Dateien und Software im KDE Repository zuzugreifen. Für einen vollständigen Überblick über die Fähigkeiten von Subversion verweisen wir auf das Buch "[http://svnbook.red-bean.com/ Version Control with Subversion (englisch)]".

== Am Anfang ==

Um das KDE Subversion Repository benutzen zu können, benötigen Sie zwei Dinge:

# Ein Subversion Client Programm
# Einen Zugang zu unserem Repository

Beachte: Für einen anonymen nur-lesen Zugriff benutzen Sie das Protokoll "svn", kein "yourname@" den Server "anonsvn.kde.org" statt dem unten genannten.

'''Subversion installieren:''' Eine Anleitung zur Installtion des Client Programms wird hier nicht gegeben. Sehen Sie in den Installtionsanleitungen Ihres Systems nach, um herauszufinden, wie man Subversion installiert. Sie benötigen mindesten Version 1.1. Wenn Sie Subversion selber compilieren und Sie auf das Repository per https (und nicht über svn+ssh) zugreifen wollen, benötigen Sie SSL und ZLIB Unterstützung und müssen daher die <tt>--with-ssl --with-zlib</tt> Option übergeben.

Alternativ können Sie auch einen der zahlreich vefügbaren graphischen Clients installieren. Diese Anleitung wendet sich an personen, die nur das <tt>svn</tt> Programm benutzen und bezieht sich dabei auf Dinge die mit dem alten <tt>cvs</tt> Programm erledigt wurden.

'''Ein Benutzerkonto bekommen:''' Hatten Sie vorher ein CVS Benutzerkonto, wurde dieses zum neuen Subversion Client migriert. Wenn nicht, sehen Sie in der [[Contribute/Get_a_SVN_Account|entsprechenden Anleitung]] nach, wie man eines bekommt.

{{Note (de)|Wenn Sie ihr CVS Passwort verloren haben, gibt es einfache Wege, dieses zu ermitteln. Benutzen Sie [http://ktown.kde.org/~coolo/cvspwd.c cvspwd.c] pder [http://kdab.net/~dfaure/cvs-unscramble cvs-unscramble] (Perl).}}

== Die Struktur des KDE Repository ==

svn.kde.org/home/kde

ist die Adresse des KDE Subversion Repositorys. Das Repository wird über das HTTPS oder SVN-SSH Protokoll angesrochen, was bedeutet, dass Ihr Passwort sicher gegenüber Abhörversuche dritter ist.

Der SSL certificate md5 fingerprint für die Repositorys ist:
F6BF EDE2 D016 D1B2 4F18 742E 2C8F B7EF

Der SSL certificate sha1 fingerprint für die Repositorys ist:
e1:e6:41:96:3c:eb:ae:78:e2:73:0d:a2:32:2f:6b:21:13:bf:3d:0f

Für Personen, die svn+ssh benutzen ist hier der Fingerprint des RSA Schlüssels des Servers:
86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb

Das Repository ist in Hauptverzeichnisse organisiert:

# /branches
# /tags
# /trunk

Man kann das Repository durchforgsten über [http://websvn.kde.org/ http://websvn.kde.org/]

=== Das Unterverzeichnis /trunk ===

Das <tt>/trunk</tt> Hauptunterverzeichnis ist dasjenige, in dem die Hauptentwicklung an KDE stattfindet. Was Sie hier finden, wird als nächstes als KDE und assoziierte Programme veröffentlicht. Hier finden Sie auch das <tt>www</tt> Modul, welches die Webpages rund um KDE beinhaltet.

<tt>/trunk</tt> ist unterteilt in folgende Unterverzeichnisse:

*<tt>KDE/</tt> KDE selber, welches die nächste Veröffentlichung werden wird. Es besteht aus folgenden Modulen:
**'''kdelibs''' - KDE Hauptbibliotheken, die von allen KDE Programmen benutzt werden
**'''kdebase''' - KDE Basisprogramme, wie das KDE Control Center, Plasma (die Oberfläche) und Konqueror (der Web Browser)
**'''kdeaccessibility''' - Accessibility Dateien
**'''kdeadmin''' - KDE Administrationsprogramme
**'''kdeartwork''' - Bilder, Themen, Sounds und andere künstlerische Dateien
**'''kdebindings''' - Bindungen für andere Sprache außer C++
**'''kdeedu''' - Erzieherische und Wissenschaftliche Programme für KDE
**'''kdegames''' - KDE Spiele
**'''kdegraphics''' - KDE Graphikapplicationen
**'''kdemultimedia''' - KDE Multimediaapplicationen
**'''kdenetwork''' - KDE Netzwerkapplicationen
**'''kdepim''' - KDE Personal Information Management Applicationen
**'''kdepimlibs''' - Biblotheken, die von KDE-PIM Applicationen benötigt werden.
**'''kdesdk''' - KDE Software Development Kit Applicationen
**'''kdetoys''' - KDE Spielzeug Applicationen
**'''kdeutils''' - Allgemeine KDE Werkzeuge
**'''kdevelop''' - Das KDevelop Programm
**'''kdevplatform''' - Die Entwicklerplatform auf der KDevelop basiert
**'''kdewebdev''' - Eine KDE Webentwicklungsapplikation
*<tt>kde-common</tt>
:Allgemeines admin/ Verzeichnis
*<tt>bugs/</tt>
:[http://bugs.kde.org/ Bugzilla] Dateien
*<tt>developer.kde.org/</tt>
:Der Inhalt von developer.kde.org
*<tt>extragear/</tt>
:KDE Programme die sich außerhalb der Haupt KDE Veröffentlichungen aufhalten
*<tt>kdereview/</tt>
:Vorübergehende Heimat für all die KDE Applikationen, von denen geglaubt wird, daß sie reif für eine Veröffentlichung sind. Von hier aus werden die Applikationen entweder nach <tt>/trunk/KDE/</tt> oder nach <tt>/trunk/extragear/</tt> verschoben, sobald die größten Probleme ausgeräumt sind.
*<tt>kdesupport/</tt>
:Unterstützende Programme und Bibliotheken für KDE
*<tt>koffice/</tt> Das KDE Office Paket, welches folgende Programme beinhaltet:
**'''karbon'''
**'''kchart'''
**'''kexi'''
**'''kformula'''
**'''kivio'''
**'''koshell'''
**'''kplato'''
**'''kpresenter'''
**'''krita'''
**'''kspread'''
**'''kugar'''
**'''kword'''
*<tt>konstruct/</tt>
:Konstruct, das KDE build Programm
*<tt>l10n-kde3/</tt>
:Übersetzungen für die "unstabilen" Module von KDE 3 (extragear, playground)
*<tt>l10n-kde4/</tt>
:Übersetzungen für KDE 4
*<tt>playground/</tt>
:Der KDE Spielplatz: Applications die gerade entwickelt werden aber noch keine Veröffentlichungsqualität erreicht haben.
*<tt>qt-copy/</tt>
:Zu Vereinfachung eine Kopie von [http://www.trolltech.com/ Trolltechs] Qt Bibliothek, auf welcher KDE basiert.
*<tt>tests/</tt>
:khtml, KOffice und ksvg Testfälle
*<tt>valgrind/</tt>
:Die Valgrind Application, welche im KDE Repository betreut wird jedoch kein Teil von KDE selber ist. Neuere Versionen von Valgrind werden in einem eigenen Repository entwickelt. Das KDE Valgrind Modul beinhaltet nur Valgrind bis zur Version 2.4.
*<tt>www/</tt>
:Webpages für die KDE Site (und verwandte Sites). Schreibzugriff auf dieses Verzeichnis ist beschränkt.

=== Das Unterverzeichnis <tt>/tags</tt> ===

Dieses Verzeichnis beinhaltet die offiziellen Veröffentlichung von den Programmen die im KDE Repository verwaltet und entwickelt werden. Jede einzelne Applikation hat hier ein Unterverzeichnis, innerhalb von diesem finden Sie die Release-Nummern.

So kann zum Beispiel der Code für KDE 3.4.0 unter <tt>/tags/KDE/3.4.0/</tt> gefunden werden.

=== Das Unterverzeichnis <tt>/branches</tt> ===

Dieses Verzeichnis beinhaltet die Zweig-versionen von Applikationen nach einer Hauptveröffentlichung.

Die meisten KDE Applikationen halten sich an die Philosophie, dass neue Features (ebenso wie neue Zeichneketten für den Benutzer) erst im nächsten Veröffentlichungszyklus — derjenige der in <tt>/trunkg/</tt> entwickelt wird — einfließen. Fehlerbereinigungen werden jedoch auf alle Applikationen angewandt, auch nach einer Veröffentlichung.

Um das zu bewerkstelligen, wird ein Zwei in dem Moment der Veröffentlichung erzeugt und zeigt damit den Status dieser Dateien zu diesem Zeitpunkt an. Fehlerbereinigungn werden dann in diese Dateien eingepflegt. Diese Zweige sind dann diejenigen die unter <tt>/branches/</tt> zu finden sind.

So kann zum Beispiel der KDE 3.4.x Zweig unter <tt>/branches/KDE/3.4/</tt> gefunden werden.

Die Unterverzeichnisse die Sie in <tt>/branches</tt> finden, sie die Unterverzeichnisse der Aplikationen wie <tt>akregator/</tt>, <tt>amarok/</tt>,
<tt>arts/</tt>, <tt>k3b/</tt>, etc. Sie finden hier auch ein <tt>KDE/</tt>
Unterverzeichnis, welches die offiziellen KDE Veröffentlichung beinhalten.

Es gibt ein spezielles Unterverzeichnis in <tt>/branches</tt> namens <tt>work/</tt>. Dieses Unterverzeichnis wird als "Arbeitszweig" berzeichnet und beinhaltet Zweige bei denen an neuen Features gearbeitet wird. Manchmal sind diese sehr experimentell. Arbeitszweige für mehrere Applikationen finden sich in <tt>/branches/work/</tt>, doch für einzelne Applikationen finden sich Arbeitszweige im jeweiligen Unterverzeichnis. Diese Entscheidung liegt bei den Entwicklern.

== Auschecken und Aktualisieren ==

=== Auschecken ===
Um entwas aus Subversion auszuchecken benutzt man das Unterkommando <tt>checkout</tt>:

'''WARNUNG:''' Wenn Sie trunk/KDE oder branches/KDE/foo auschecken werden Sie auch die komplette kde-i18n herunterladen!

Angenommen Sie wollen nur KDevelop aus dem KDE Repository auschecken, würden Sie folgende Kommandos eingeben:

CVS Kommando:
cvs -d :pserver:yourname@cvs.kde.org:/home/kde login
cvs -d :pserver:yourname@cvs.kde.org:/home/kde checkout kdevelop

Subversion Kommando:

CVS Benutzer die einen ssh Zugang besitzen, sollten das Protokoll svn+ssh,
CVS Benutzer, die einen Passwortzugang benutzen sollten das Protokoll https im folgenden benutzen.

svn checkout <protocol>://<username>@svn.kde.org/home/kde/trunk/KDE/kdevelop

=== Aktualisieren ===
Um zu aktualisieren, benutzen Sie das <tt>update</tt> Unterkommando.

Hier gibt es keinen Unterschied zu CVS: Sie wechseln in ihre ausgecheckte lokale Kopie (für diejenigen, für die das alles neu ist: die ausgecheckte Kopie sollte sich in Ihrem Heimatordner befinden) und geben ein <tt>svn update</tt> Kommando (oder kürzer <tt>svn up</tt>).

== Den Status einer Datei ermitteln ==

Um herauszufinden welche lokalen Dateien verändert wurden, haben die meisten unter CVS das Kommando cvs up aufgerufen und dann diejenigen Dateien gesucht, die mit einem '''M''' markiert waren. Das funktioniert unter svn nicht, daher müssen Sie das Kommando <tt>svn status</tt> aufrufen, um den Status der Dateien zu ermitteln.

== Ins Repository hochladen ==

Um Änderungen hochzuladen ruft man, ähnlich wie bei CVS, die Unterkommandos <tt>commit</tt> oder <tt>checkin</tt> (Kurzversion davon <tt>ci</tt>) auf.

CVS Kommando:
cvs commit
# oder
cvs ci
# oder
cvs ci filename.cpp

Subversion Kommando:
svn commit
# oder
svn ci
# oder
svn ci filename.cpp

Auf diese Weise wird <tt>svn</tt> den in <tt>$SVN_EDITOR</tt> eingetragenen Texteditor aufrufen, damit Sie das Änderungsprotokoll ausfüllen können. Wenn Sie es vorziehen, können Sie <tt>svn</tt> auch über die -m Option eine vollständige Mitteilung übergeben:

svn ci -m "Updating protocol to conform to HTTP/1.1"

== Dateien ignorieren ==

Subversion stores ignored files per directory. To edit the ignored
files of the directory you are currently in, do
svn propedit svn:ignore .
that will launch your editor, write there the names of the files you want to
ignore, one file per line. Once you are done, do a commit so the ignored list
file gets updated on the server.

A lot of files were ignored in CVS with help from global ignore list which
is not supported yet by SVN. You can wait for svn 1.3 or you need to add the
ignore list to the [miscellany] group in your {{path|~/.subversion/config}} (all in
one line):

global-ignores = *.o *.lo *.la .*.rej *.rej .*~ *~ .#* #*# .DS_Store *.moc
*.moc.cc *.moc.cpp config.log config.status config.cache *.gmo .deps .libs
SunWS_cache *.lo *.la *.rpo *.la.closure *_la_closure.cpp *_la_closure.cc
*_la_closure.cxx *.all_cc.cc *.all_cpp.cpp *.all_C.C *.all_cxx.cxx
*_meta_unload.cc *_meta_unload.h *_meta_unload.cpp *_meta_unload.C
*_meta_unload.cxx index.cache.bz2 .memdump Makefile.rules.in Makefile.calls.in
Makefile.rules Makefile.calls autom4te.cache *.kidl

== Working with multiple revisions and branches ==

Unlike CVS, Subversion doesn't generate a revision number for each file
modified. Instead, the full repository is versioned, as a whole. This way, a
given revision number represents the state the repository was on a given date.
In other words, a revision number is like a timestamp (in fact, the Subversion
server uses this fact to search for dates in the repository faster).

So, for instance, when you check out the KDE repository, Subversion will
tell you the following:

Updated to revision 403821.

This means that the latest revision available at the time of the operation
was 403821. If you make a modification and commit, Subversion will update the
server-side revision and will inform you of it. Like CVS, only the committed
files will be updated: you will need run <tt>cvs up</tt> to update the rest of the
files.

If you want to retrieve a specific revision of a file, you can use the <tt>-r</tt>
switch. Besides the revision number itself, -r accepts a number of other
possibilities:

* The revision number: for example, use -r 403819 to retrieve that version
* '''BASE''': the revision you updated to
* '''COMMITTED''': the revision a file was last modified, before BASE
* '''PREV''': the revision of the previous commit to the file before COMMITTED
* '''HEAD''': the most recent revision available in the server
* '''{ date }''': between curly brackets, you can specify a date for searching the closest revisions

The following illustrates the evolution of the keywords:

# You run <tt>svn up</tt> to update to the latest available revision. Suppose Subversion tells you it updated to revision 403821. This means that HEAD and BASE are 403821.
# You modify file README and commit it. Suppose Subversion tells you it committed revision 403822. This means HEAD, BASE and COMMITTED are 403822.
# You modify the file again and commit it. Now PREV is 403822, but HEAD, BASE and COMMITTED are updated to a new value (suppose it's 403823).
# Now someone else modifies the repository, and you update your working copy. If Subversion tells you it updated to 403824, this means now HEAD and BASE are moved to 403824 (but PREV and COMMITTED stay the same)
# If someone modifies the README file now, HEAD is moved. The other keywords stay the same for you, until you update. At this time, we will have HEAD = 403825 (the latest available revision), BASE = 403824 (the revision you last updated to), COMMITTED = 403823 (the revision of the latest change to the file when you last updated) and PREV = 403822 (the revision of the change before COMMITTED)

Those keywords are useful to retrieve logs and diffs for commits to the
repository.

If you want to see the difference between your working copy and BASE, you
can run:

svn diff

This is a very fast operation, since Subversion keeps a local copy of BASE.
It doesn't need a network connection to accomplish this operation.

If you want to see the difference between your local copy and the latest
available on the server, you will run:

svn diff -r HEAD

If you want to see what has changed in the repository since you've last updated, you can use:
svn diff -r BASE:HEAD

If you want to see the last change to a file before BASE, you can use:
svn diff -r PREV:BASE
# or
svn diff -r PREV:COMMITTED

That is also valid for the <tt>svn log</tt> command.

== Unterverzeichnisse von anderen Orten verlinken ==

It can happen you would like to include a copy of a subdirectory from another place, but just for convenience, not for developing the code in there. Of course it should be updated automatically whenever the original changes. Subversion can help you. You need to edit the property <tt>svn:external</tt> of the directory the subdirectory should be added to. So for the current directory you use
svn propedit svn:externals .
and then enter lines of the form
libkhalkhi svn://anonsvn.kde.org/home/kde/trunk/playground/pim/khalkhi
Updating will now fetch <tt>/trunk/playground/pim/khalkhi</tt> into the subdirectoy <tt>libkhalkhi</tt>.

{{warning (de)|Beware that you cannot commit changes you did to the local copy of the external subdirectory, it is just a readonly copy.}}

You use <tt>svn://anonsvn.kde.org</tt> and not another protocol, because <tt>anonsvn.kde.org</tt> is accessible to everyone. Using <tt>https:</tt> or <tt>svn+ssh:</tt> would only work for users of that protocol. There are still some small disadvantage with <tt>anonsvn.kde.org</tt>: It is not always in synchronization with <tt>svn.kde.org</tt>, so updates in the original branch may take a while to appear on <tt>anonsvn.kde.org</tt>. And some strict firewalls are blocking the <tt>svn:</tt> protocol.

A special case in KDE 3 is the subdirectory <tt>admin</tt>, containing the KDE 3 build utilities. It is linked in to the top directory in all modules, and maintained in <tt>/branches/KDE/3.5/kde-common</tt>. For <tt>admin</tt> the KDE subversion server is configured to allow readonly access for everyone, so if you see
admin https://svn.kde.org/home/kde/branches/KDE/3.5/kde-common/admin
there is no need to change this.

== Mehr Informationen im KDE Wiki ==

Siehe auch [http://wiki.kde.org/tiki-index.php?page=KDE%20Subversion%20HOWTO the KDE wiki] für mehr Informationen über Subversion in KDE

Getting Started/Sources/Subversion (de)

2008-03-09T15:55:13Z

DrSlowDecay: Some more translation

{{Template:I18n/Language Navigation Bar|Getting Started/Sources/Using Subversion with KDE}}

{{TutorialBrowser (de)|

series=Anfang|

name=Subversion mit KDE benutzen|
}}

== Zusammenfassung ==

Der folgende Text ist eine schnelle kde-spezifische Einführung, wie man Subversion benutzt, um auf Dateien und Software im KDE Repository zuzugreifen. Für einen vollständigen Überblick über die Fähigkeiten von Subversion verweisen wir auf das Buch "[http://svnbook.red-bean.com/ Version Control with Subversion (englisch)]".

== Am Anfang ==

Um das KDE Subversion Repository benutzen zu können, benötigen Sie zwei Dinge:

# Ein Subversion Client Programm
# Einen Zugang zu unserem Repository

Beachte: Für einen anonymen nur-lesen Zugriff benutzen Sie das Protokoll "svn", kein "yourname@" den Server "anonsvn.kde.org" statt dem unten genannten.

'''Subversion installieren:''' Eine Anleitung zur Installtion des Client Programms wird hier nicht gegeben. Sehen Sie in den Installtionsanleitungen Ihres Systems nach, um herauszufinden, wie man Subversion installiert. Sie benötigen mindesten Version 1.1. Wenn Sie Subversion selber compilieren und Sie auf das Repository per https (und nicht über svn+ssh) zugreifen wollen, benötigen Sie SSL und ZLIB Unterstützung und müssen daher die <tt>--with-ssl --with-zlib</tt> Option übergeben.

Alternativ können Sie auch einen der zahlreich vefügbaren graphischen Clients installieren. Diese Anleitung wendet sich an personen, die nur das <tt>svn</tt> Programm benutzen und bezieht sich dabei auf Dinge die mit dem alten <tt>cvs</tt> Programm erledigt wurden.

'''Ein Benutzerkonto bekommen:''' Hatten Sie vorher ein CVS Benutzerkonto, wurde dieses zum neuen Subversion Client migriert. Wenn nicht, sehen Sie in der [[Contribute/Get_a_SVN_Account|entsprechenden Anleitung]] nach, wie man eines bekommt.

{{Note (de)|Wenn Sie ihr CVS Passwort verloren haben, gibt es einfache Wege, dieses zu ermitteln. Benutzen Sie [http://ktown.kde.org/~coolo/cvspwd.c cvspwd.c] pder [http://kdab.net/~dfaure/cvs-unscramble cvs-unscramble] (Perl).}}

== Die Struktur des KDE Repository ==

svn.kde.org/home/kde

ist die Adresse des KDE Subversion Repositorys. Das Repository wird über das HTTPS oder SVN-SSH Protokoll angesrochen, was bedeutet, dass Ihr Passwort sicher gegenüber Abhörversuche dritter ist.

Der SSL certificate md5 fingerprint für die Repositorys ist:
F6BF EDE2 D016 D1B2 4F18 742E 2C8F B7EF

Der SSL certificate sha1 fingerprint für die Repositorys ist:
e1:e6:41:96:3c:eb:ae:78:e2:73:0d:a2:32:2f:6b:21:13:bf:3d:0f

Für Personen, die svn+ssh benutzen ist hier der Fingerprint des RSA Schlüssels des Servers:
86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb

Das Repository ist in Hauptverzeichnisse organisiert:

# /branches
# /tags
# /trunk

Man kann das Repository durchforgsten über [http://websvn.kde.org/ http://websvn.kde.org/]

=== Das Unterverzeichnis /trunk ===

Das <tt>/trunk</tt> Hauptunterverzeichnis ist dasjenige, in dem die Hauptentwicklung an KDE stattfindet. Was Sie hier finden, wird als nächstes als KDE und assoziierte Programme veröffentlicht. Hier finden Sie auch das <tt>www</tt> Modul, welches die Webpages rund um KDE beinhaltet.

<tt>/trunk</tt> ist unterteilt in folgende Unterverzeichnisse:

*<tt>KDE/</tt> KDE selber, welches die nächste Veröffentlichung werden wird. Es besteht aus folgenden Modulen:
**'''kdelibs''' - KDE Hauptbibliotheken, die von allen KDE Programmen benutzt werden
**'''kdebase''' - KDE Basisprogramme, wie das KDE Control Center, Plasma (die Oberfläche) und Konqueror (der Web Browser)
**'''kdeaccessibility''' - Accessibility Dateien
**'''kdeadmin''' - KDE Administrationsprogramme
**'''kdeartwork''' - Bilder, Themen, Sounds und andere künstlerische Dateien
**'''kdebindings''' - Bindungen für andere Sprache außer C++
**'''kdeedu''' - Erzieherische und Wissenschaftliche Programme für KDE
**'''kdegames''' - KDE Spiele
**'''kdegraphics''' - KDE Graphikapplicationen
**'''kdemultimedia''' - KDE Multimediaapplicationen
**'''kdenetwork''' - KDE Netzwerkapplicationen
**'''kdepim''' - KDE Personal Information Management Applicationen
**'''kdepimlibs''' - Biblotheken, die von KDE-PIM Applicationen benötigt werden.
**'''kdesdk''' - KDE Software Development Kit Applicationen
**'''kdetoys''' - KDE Spielzeug Applicationen
**'''kdeutils''' - Allgemeine KDE Werkzeuge
**'''kdevelop''' - Das KDevelop Programm
**'''kdevplatform''' - Die Entwicklerplatform auf der KDevelop basiert
**'''kdewebdev''' - Eine KDE Webentwicklungsapplikation
*<tt>kde-common</tt>
:Allgemeines admin/ Verzeichnis
*<tt>bugs/</tt>
:[http://bugs.kde.org/ Bugzilla] Dateien
*<tt>developer.kde.org/</tt>
:Der Inhalt von developer.kde.org
*<tt>extragear/</tt>
:KDE Programme die sich außerhalb der Haupt KDE Veröffentlichungen aufhalten
*<tt>kdereview/</tt>
:Vorübergehende Heimat für all die KDE Applikationen, von denen geglaubt wird, daß sie reif für eine Veröffentlichung sind. Von hier aus werden die Applikationen entweder nach <tt>/trunk/KDE/</tt> oder nach <tt>/trunk/extragear/</tt> verschoben, sobald die größten Probleme ausgeräumt sind.
*<tt>kdesupport/</tt>
:Unterstützende Programme und Bibliotheken für KDE
*<tt>koffice/</tt> Das KDE Office Paket, welches folgende Programme beinhaltet:
**'''karbon'''
**'''kchart'''
**'''kexi'''
**'''kformula'''
**'''kivio'''
**'''koshell'''
**'''kplato'''
**'''kpresenter'''
**'''krita'''
**'''kspread'''
**'''kugar'''
**'''kword'''
*<tt>konstruct/</tt>
:Konstruct, das KDE build Programm
*<tt>l10n-kde3/</tt>
:Übersetzungen für die "unstabilen" Module von KDE 3 (extragear, playground)
*<tt>l10n-kde4/</tt>
:Übersetzungen für KDE 4
*<tt>playground/</tt>
:Der KDE Spielplatz: Applications die gerade entwickelt werden aber noch keine Veröffentlichungsqualität erreicht haben.
*<tt>qt-copy/</tt>
:Zu Vereinfachung eine Kopie von [http://www.trolltech.com/ Trolltechs] Qt Bibliothek, auf welcher KDE basiert.
*<tt>tests/</tt>
:khtml, KOffice und ksvg Testfälle
*<tt>valgrind/</tt>
:Die Valgrind Application, welche im KDE Repository betreut wird jedoch kein Teil von KDE selber ist. Neuere Versionen von Valgrind werden in einem eigenen Repository entwickelt. Das KDE Valgrind Modul beinhaltet nur Valgrind bis zur Version 2.4.
*<tt>www/</tt>
:Webpages für die KDE Site (und verwandte Sites). Schreibzugriff auf dieses Verzeichnis ist beschränkt.

=== Das Unterverzeichnis <tt>/tags</tt> ===

Dieses Verzeichnis beinhaltet die offiziellen Veröffentlichung von den Programmen die im KDE Repository verwaltet und entwickelt werden. Jede einzelne Applikation hat hier ein Unterverzeichnis, innerhalb von diesem finden Sie die Release-Nummern.

So kann zum Beispiel der Code für KDE 3.4.0 unter <tt>/tags/KDE/3.4.0/</tt> gefunden werden.

=== Das Unterverzeichnis <tt>/branches</tt> ===

Dieses Verzeichnis beinhaltet die Zweig-versionen von Applikationen nach einer Hauptveröffentlichung.

Die meisten KDE Applikationen halten sich an die Philosophie, dass neue Features (ebenso wie neue Zeichneketten für den Benutzer) erst im nächsten Veröffentlichungszyklus — derjenige der in <tt>/trunkg/</tt> entwickelt wird — einfließen. Fehlerbereinigungen werden jedoch auf alle Applikationen angewandt, auch nach einer Veröffentlichung.

Um das zu bewerkstelligen, wird ein Zwei in dem Moment der Veröffentlichung erzeugt und zeigt damit den Status dieser Dateien zu diesem Zeitpunkt an. Fehlerbereinigungn werden dann in diese Dateien eingepflegt. Diese Zweige sind dann diejenigen die unter <tt>/branches/</tt> zu finden sind.

So kann zum Beispiel der KDE 3.4.x Zweig unter <tt>/branches/KDE/3.4/</tt> gefunden werden.

Die Unterverzeichnisse die Sie in <tt>/branches</tt> finden, sie die Unterverzeichnisse der Aplikationen wie <tt>akregator/</tt>, <tt>amarok/</tt>,
<tt>arts/</tt>, <tt>k3b/</tt>, etc. Sie finden hier auch ein <tt>KDE/</tt>
Unterverzeichnis, welches die offiziellen KDE Veröffentlichung beinhalten.

Es gibt ein spezielles Unterverzeichnis in <tt>/branches</tt> namens <tt>work/</tt>. Dieses Unterverzeichnis wird als "Arbeitszweig" berzeichnet und beinhaltet Zweige bei denen an neuen Features gearbeitet wird. Manchmal sind diese sehr experimentell. Arbeitszweige für mehrere Applikationen finden sich in <tt>/branches/work/</tt>, doch für einzelne Applikationen finden sich Arbeitszweige im jeweiligen Unterverzeichnis. Diese Entscheidung liegt bei den Entwicklern.

== Auschecken und Aktualisieren ==

=== Auschecken ===
Um entwas aus Subversion auszuchecken benutzt man das Unterkommando <tt>checkout</tt>:

'''WARNUNG:''' Wenn Sie trunk/KDE oder branches/KDE/foo auschecken werden Sie auch die komplette kde-i18n herunterladen!

Angenommen Sie wollen nur KDevelop aus dem KDE Repository auschecken, würden Sie folgende Kommandos eingeben:

CVS Kommando:
cvs -d :pserver:yourname@cvs.kde.org:/home/kde login
cvs -d :pserver:yourname@cvs.kde.org:/home/kde checkout kdevelop

Subversion Kommando:

CVS Benutzer die einen ssh Zugang besitzen, sollten das Protokoll svn+ssh,
CVS Benutzer, die einen Passwortzugang benutzen sollten das Protokoll https im folgenden benutzen.

svn checkout <protocol>://<username>@svn.kde.org/home/kde/trunk/KDE/kdevelop

=== Aktualisieren ===

In order to update, you use the <tt>update</tt> subcommand.

This is no different from CVS: you change into your checked out copy (for those new to this whole process, the checked out copy should be in your Home folder) and issue a <tt>svn update</tt> (or, shorter, <tt>svn up</tt>) command.

== Den Status einer Datei ermitteln ==

To know which local files you had modified, in CVS most people did
cvs up
and looked at the files with '''M''', this does not work with svn so you have to do
svn status
to know the status of the files.

== Ins Repository hochladen ==

Just like in CVS, committing to the Subversion repository is accomplished
with the <tt>commit</tt> or <tt>checkin</tt> (<tt>ci</tt> for short) subcommands.

CVS command:
cvs commit
# or
cvs ci
# or
cvs ci filename.cpp

Subversion command:
svn commit
# or
svn ci
# or
svn ci filename.cpp

This way, <tt>svn</tt> will launch the editor specified in <tt>$SVN_EDITOR</tt> for you
to compose the commit message. If you prefer, you can give <tt>svn</tt> the -m
oprtion with your full message:

svn ci -m "Updating protocol to conform to HTTP/1.1"

== Dateien ignorieren ==

Subversion stores ignored files per directory. To edit the ignored
files of the directory you are currently in, do
svn propedit svn:ignore .
that will launch your editor, write there the names of the files you want to
ignore, one file per line. Once you are done, do a commit so the ignored list
file gets updated on the server.

A lot of files were ignored in CVS with help from global ignore list which
is not supported yet by SVN. You can wait for svn 1.3 or you need to add the
ignore list to the [miscellany] group in your {{path|~/.subversion/config}} (all in
one line):

global-ignores = *.o *.lo *.la .*.rej *.rej .*~ *~ .#* #*# .DS_Store *.moc
*.moc.cc *.moc.cpp config.log config.status config.cache *.gmo .deps .libs
SunWS_cache *.lo *.la *.rpo *.la.closure *_la_closure.cpp *_la_closure.cc
*_la_closure.cxx *.all_cc.cc *.all_cpp.cpp *.all_C.C *.all_cxx.cxx
*_meta_unload.cc *_meta_unload.h *_meta_unload.cpp *_meta_unload.C
*_meta_unload.cxx index.cache.bz2 .memdump Makefile.rules.in Makefile.calls.in
Makefile.rules Makefile.calls autom4te.cache *.kidl

== Working with multiple revisions and branches ==

Unlike CVS, Subversion doesn't generate a revision number for each file
modified. Instead, the full repository is versioned, as a whole. This way, a
given revision number represents the state the repository was on a given date.
In other words, a revision number is like a timestamp (in fact, the Subversion
server uses this fact to search for dates in the repository faster).

So, for instance, when you check out the KDE repository, Subversion will
tell you the following:

Updated to revision 403821.

This means that the latest revision available at the time of the operation
was 403821. If you make a modification and commit, Subversion will update the
server-side revision and will inform you of it. Like CVS, only the committed
files will be updated: you will need run <tt>cvs up</tt> to update the rest of the
files.

If you want to retrieve a specific revision of a file, you can use the <tt>-r</tt>
switch. Besides the revision number itself, -r accepts a number of other
possibilities:

* The revision number: for example, use -r 403819 to retrieve that version
* '''BASE''': the revision you updated to
* '''COMMITTED''': the revision a file was last modified, before BASE
* '''PREV''': the revision of the previous commit to the file before COMMITTED
* '''HEAD''': the most recent revision available in the server
* '''{ date }''': between curly brackets, you can specify a date for searching the closest revisions

The following illustrates the evolution of the keywords:

# You run <tt>svn up</tt> to update to the latest available revision. Suppose Subversion tells you it updated to revision 403821. This means that HEAD and BASE are 403821.
# You modify file README and commit it. Suppose Subversion tells you it committed revision 403822. This means HEAD, BASE and COMMITTED are 403822.
# You modify the file again and commit it. Now PREV is 403822, but HEAD, BASE and COMMITTED are updated to a new value (suppose it's 403823).
# Now someone else modifies the repository, and you update your working copy. If Subversion tells you it updated to 403824, this means now HEAD and BASE are moved to 403824 (but PREV and COMMITTED stay the same)
# If someone modifies the README file now, HEAD is moved. The other keywords stay the same for you, until you update. At this time, we will have HEAD = 403825 (the latest available revision), BASE = 403824 (the revision you last updated to), COMMITTED = 403823 (the revision of the latest change to the file when you last updated) and PREV = 403822 (the revision of the change before COMMITTED)

Those keywords are useful to retrieve logs and diffs for commits to the
repository.

If you want to see the difference between your working copy and BASE, you
can run:

svn diff

This is a very fast operation, since Subversion keeps a local copy of BASE.
It doesn't need a network connection to accomplish this operation.

If you want to see the difference between your local copy and the latest
available on the server, you will run:

svn diff -r HEAD

If you want to see what has changed in the repository since you've last updated, you can use:
svn diff -r BASE:HEAD

If you want to see the last change to a file before BASE, you can use:
svn diff -r PREV:BASE
# or
svn diff -r PREV:COMMITTED

That is also valid for the <tt>svn log</tt> command.

== Unterverzeichnisse von anderen Orten verlinken ==

It can happen you would like to include a copy of a subdirectory from another place, but just for convenience, not for developing the code in there. Of course it should be updated automatically whenever the original changes. Subversion can help you. You need to edit the property <tt>svn:external</tt> of the directory the subdirectory should be added to. So for the current directory you use
svn propedit svn:externals .
and then enter lines of the form
libkhalkhi svn://anonsvn.kde.org/home/kde/trunk/playground/pim/khalkhi
Updating will now fetch <tt>/trunk/playground/pim/khalkhi</tt> into the subdirectoy <tt>libkhalkhi</tt>.

{{warning (de)|Beware that you cannot commit changes you did to the local copy of the external subdirectory, it is just a readonly copy.}}

You use <tt>svn://anonsvn.kde.org</tt> and not another protocol, because <tt>anonsvn.kde.org</tt> is accessible to everyone. Using <tt>https:</tt> or <tt>svn+ssh:</tt> would only work for users of that protocol. There are still some small disadvantage with <tt>anonsvn.kde.org</tt>: It is not always in synchronization with <tt>svn.kde.org</tt>, so updates in the original branch may take a while to appear on <tt>anonsvn.kde.org</tt>. And some strict firewalls are blocking the <tt>svn:</tt> protocol.

A special case in KDE 3 is the subdirectory <tt>admin</tt>, containing the KDE 3 build utilities. It is linked in to the top directory in all modules, and maintained in <tt>/branches/KDE/3.5/kde-common</tt>. For <tt>admin</tt> the KDE subversion server is configured to allow readonly access for everyone, so if you see
admin https://svn.kde.org/home/kde/branches/KDE/3.5/kde-common/admin
there is no need to change this.

== Mehr Informationen im KDE Wiki ==

Siehe auch [http://wiki.kde.org/tiki-index.php?page=KDE%20Subversion%20HOWTO the KDE wiki] für mehr Informationen über Subversion in KDE

Getting Started/Sources/Subversion (de)

2008-01-31T16:02:44Z

DrSlowDecay: Some more translation

{{Template:I18n/Language Navigation Bar|Getting Started/Sources/Using Subversion with KDE}}

{{TutorialBrowser (de)|

series=Anfang|

name=Subversion mit KDE benutzen|
}}

== Zusammenfassung ==

Der folgende Text ist eine schnelle kde-spezifische Einführung, wie man Subversion benutzt, um auf Dateien und Software im KDE Repository zuzugreifen. Für einen vollständigen Überblick über die Fähigkeiten von Subversion verweisen wir auf das Buch "[http://svnbook.red-bean.com/ Version Control with Subversion (englisch)]".

== Am Anfang ==

Um das KDE Subversion Repository benutzen zu können, benötigen Sie zwei Dinge:

# Ein Subversion Client Programm
# Einen Zugang zu unserem Repository

Beachte: Für einen anonymen nur-lesen Zugriff benutzen Sie das Protokoll "svn", kein "yourname@" den Server "anonsvn.kde.org" statt dem unten genannten.

'''Subversion installieren:''' Eine Anleitung zur Installtion des Client Programms wird hier nicht gegeben. Sehen Sie in den Installtionsanleitungen Ihres Systems nach, um herauszufinden, wie man Subversion installiert. Sie benötigen mindesten Version 1.1. Wenn Sie Subversion selber compilieren und Sie auf das Repository per https (und nicht über svn+ssh) zugreifen wollen, benötigen Sie SSL und ZLIB Unterstützung und müssen daher die <tt>--with-ssl --with-zlib</tt> Option übergeben.

Alternativ können Sie auch einen der zahlreich vefügbaren graphischen Clients installieren. Diese Anleitung wendet sich an personen, die nur das <tt>svn</tt> Programm benutzen und bezieht sich dabei auf Dinge die mit dem alten <tt>cvs</tt> Programm erledigt wurden.

'''Ein Benutzerkonto bekommen:''' Hatten Sie vorher ein CVS Benutzerkonto, wurde dieses zum neuen Subversion Client migriert. Wenn nicht, sehen Sie in der [[Contribute/Get_a_SVN_Account|entsprechenden Anleitung]] nach, wie man eines bekommt.

{{Note (de)|Wenn Sie ihr CVS Passwort verloren haben, gibt es einfache Wege, dieses zu ermitteln. Benutzen Sie [http://ktown.kde.org/~coolo/cvspwd.c cvspwd.c] pder [http://kdab.net/~dfaure/cvs-unscramble cvs-unscramble] (Perl).}}

== Die Struktur des KDE Repository ==

svn.kde.org/home/kde

ist die Adresse des KDE Subversion Repositorys. Das Repository wird über das HTTPS oder SVN-SSH Protokoll angesrochen, was bedeutet, dass Ihr Passwort sicher gegenüber Abhörversuche dritter ist.

Der SSL certificate md5 fingerprint für die Repositorys ist:
F6BF EDE2 D016 D1B2 4F18 742E 2C8F B7EF

Der SSL certificate sha1 fingerprint für die Repositorys ist:
e1:e6:41:96:3c:eb:ae:78:e2:73:0d:a2:32:2f:6b:21:13:bf:3d:0f

Für Personen, die svn+ssh benutzen ist hier der Fingerprint des RSA Schlüssels des Servers:
86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb

Das Repository ist in Hauptverzeichnisse organisiert:

# /branches
# /tags
# /trunk

Man kann das Repository durchforgsten über [http://websvn.kde.org/ http://websvn.kde.org/]

=== Das Unterverzeichnis /trunk ===

The <tt>/trunk</tt>
top-level subdirectory is where the main development for KDE occurs.
What you will find here is what will become the next KDE release, and
its associated programs. Here you will also find the <tt>www</tt> module,
which contains webpages for KDE's site and related ones.

<tt>/trunk</tt> is further subdivided into these sub-directories:

*<tt>KDE/</tt> KDE itself, what will become the next public release. It contains the following modules:
**'''kdelibs''' - KDE basic libraries, used by all KDE programs
**'''kdebase''' - KDE base programs, like the KDE Control Center, Kicker (the panel) and Konqueror (the web browser)
**'''kdeaccessibility''' - Accessibility files
**'''kdeadmin''' - KDE Administration applications
**'''kdeartwork''' - Images, themes, sounds and other art files
**'''kdebindings''' - Bindings for languages other than C++
**'''kdeedu''' - KDE Educational applications
**'''kdegames''' - KDE Games
**'''kdegraphics''' - KDE Graphical applications
**'''kdemultimedia''' - KDE Multimedia applications
**'''kdenetwork''' - KDE Networking applications
**'''kdepim''' - KDE Personal Information Management applications
**'''kdepimlibs''' - Libraries used by KDE-PIM applications.
**'''kdesdk''' - KDE Software Development Kit applications
**'''kdetoys''' - KDE toy applications
**'''kdeutils''' - KDE General utilities
**'''kdevelop''' - The KDevelop program
**'''kdevplatform''' - The development platform which KDevelop is based on
**'''kdewebdev''' - KDE Web development applications
*<tt>kde-common</tt>
:Common admin/ directory
*<tt>bugs/</tt>
:[http://bugs.kde.org/ Bugzilla] files
*<tt>developer.kde.org/</tt>
:The content of developer.kde.org
*<tt>extragear/</tt>
:KDE programs outside the main KDE releases.
*<tt>kdereview/</tt>
:Temporary home for KDE applications that are believed to have reached release-quality. From here, once all major issues are resolved, applications are moved either to <tt>/trunk/KDE/</tt> or to <tt>/trunk/extragear/</tt>
*<tt>kdesupport/</tt>
:Supporting applications and libraries for KDE
*<tt>koffice/</tt> The KDE Office suite, containing the programs:
**'''karbon'''
**'''kchart'''
**'''kexi'''
**'''kformula'''
**'''kivio'''
**'''koshell'''
**'''kplato'''
**'''kpresenter'''
**'''krita'''
**'''kspread'''
**'''kugar'''
**'''kword'''
*<tt>konstruct/</tt>
:Konstruct, the KDE build program
*<tt>l10n-kde3/</tt>
:Translations for the "unstable" modules of KDE 3 (extragear, playground)
*<tt>l10n-kde4/</tt>
:Translations for KDE 4
*<tt>playground/</tt>
:The KDE playground: applications being developed, but not having yet reached release-quality.
*<tt>qt-copy/</tt>
:The convenience copy of [http://www.trolltech.com/ Trolltech's] Qt library, which KDE is based upon.
*<tt>tests/</tt>
:khtml, KOffice and ksvg testcases
*<tt>valgrind/</tt>
:The Valgrind application, which is hosted on the KDE repository, but that is not part of KDE itself. Note that newer versions of Valgrind are developed on their own repository. The KDE Valgrind modules only holds up to Valgrind 2.4.
*<tt>www/</tt>
:Webpages for the KDE site (and related sites). Write access to this directory is restricted.

=== Das Unterverzeichnis <tt>/tags</tt> ===

This
directory contains the official releases of the programs maintained and
developed in the KDE repository. Each individual application has a
subdirectory here. Inside it, you will find the release numbers.

For instance, the KDE 3.4.0 code can be found under <tt>/tags/KDE/3.4.0/</tt>.

=== Das Unterverzeichnis <tt>/branches</tt> ===

This directory contains the branch versions of the applications after a major release.

Most
KDE applications adhere to the philosphy that new features (as well as
new user-visible strings) are added only to the next release cycle —
the one that lives in <tt>/trunk/</tt>. However, bugfixes are applied to all
applications, even after release.

In
order to do that, a branch is created at the moment of the release,
indicating the state of the files at that time. Bugfixes are then
checked in to those files. Those branches are the ones in <tt>/branches/</tt>.

For instance, the KDE 3.4.x branch can be found under <tt>/branches/KDE/3.4/</tt>

The subdirectories you will find inside <tt>/branches</tt> are the
application subdirs, like <tt>akregator/</tt>, <tt>amarok/</tt>,
<tt>arts/</tt>, <tt>k3b/</tt>, etc. You will also find a <tt>KDE/</tt>
subdir, containing the official KDE releases since time immemorial.

One special subdir is found in <tt>/branches</tt>: <tt>work/</tt>. This
subdir contains the so-called "work branches", that is, branches containing
features being worked on, sometimes highly experimental. Multi-application
work branches always are checked in to <tt>/branches/work/</tt>, but
single-application branches may be found in each application's subdir. That
is a decision left to the developers.

== Auschecken und Aktualisieren ==

=== Auschecken ===
In order to check out something with Subversion, you use the <tt>checkout</tt> subcommand.

'''WARNING:''' If you checkout trunk/KDE/ or branches/KDE/foo/ you will download complete kde-i18n!

Suppose you wanted to check out only KDevelop from the KDE repository. You would do:

CVS command:
cvs -d :pserver:yourname@cvs.kde.org:/home/kde login
cvs -d :pserver:yourname@cvs.kde.org:/home/kde checkout kdevelop

Subversion command:

CVS users currently using ssh access, should use protocol svn+ssh,
CVS users currently using password access, should use protocol https
in the following.

svn checkout <protocol>://<username>@svn.kde.org/home/kde/trunk/KDE/kdevelop

=== Aktualisieren ===

In order to update, you use the <tt>update</tt> subcommand.

This is no different from CVS: you change into your checked out copy (for those new to this whole process, the checked out copy should be in your Home folder) and issue a <tt>svn update</tt> (or, shorter, <tt>svn up</tt>) command.

== Den Status einer Datei ermitteln ==

To know which local files you had modified, in CVS most people did
cvs up
and looked at the files with '''M''', this does not work with svn so you have to do
svn status
to know the status of the files.

== Ins Repository hochladen ==

Just like in CVS, committing to the Subversion repository is accomplished
with the <tt>commit</tt> or <tt>checkin</tt> (<tt>ci</tt> for short) subcommands.

CVS command:
cvs commit
# or
cvs ci
# or
cvs ci filename.cpp

Subversion command:
svn commit
# or
svn ci
# or
svn ci filename.cpp

This way, <tt>svn</tt> will launch the editor specified in <tt>$SVN_EDITOR</tt> for you
to compose the commit message. If you prefer, you can give <tt>svn</tt> the -m
oprtion with your full message:

svn ci -m "Updating protocol to conform to HTTP/1.1"

== Dateien ignorieren ==

Subversion stores ignored files per directory. To edit the ignored
files of the directory you are currently in, do
svn propedit svn:ignore .
that will launch your editor, write there the names of the files you want to
ignore, one file per line. Once you are done, do a commit so the ignored list
file gets updated on the server.

A lot of files were ignored in CVS with help from global ignore list which
is not supported yet by SVN. You can wait for svn 1.3 or you need to add the
ignore list to the [miscellany] group in your {{path|~/.subversion/config}} (all in
one line):

global-ignores = *.o *.lo *.la .*.rej *.rej .*~ *~ .#* #*# .DS_Store *.moc
*.moc.cc *.moc.cpp config.log config.status config.cache *.gmo .deps .libs
SunWS_cache *.lo *.la *.rpo *.la.closure *_la_closure.cpp *_la_closure.cc
*_la_closure.cxx *.all_cc.cc *.all_cpp.cpp *.all_C.C *.all_cxx.cxx
*_meta_unload.cc *_meta_unload.h *_meta_unload.cpp *_meta_unload.C
*_meta_unload.cxx index.cache.bz2 .memdump Makefile.rules.in Makefile.calls.in
Makefile.rules Makefile.calls autom4te.cache *.kidl

== Working with multiple revisions and branches ==

Unlike CVS, Subversion doesn't generate a revision number for each file
modified. Instead, the full repository is versioned, as a whole. This way, a
given revision number represents the state the repository was on a given date.
In other words, a revision number is like a timestamp (in fact, the Subversion
server uses this fact to search for dates in the repository faster).

So, for instance, when you check out the KDE repository, Subversion will
tell you the following:

Updated to revision 403821.

This means that the latest revision available at the time of the operation
was 403821. If you make a modification and commit, Subversion will update the
server-side revision and will inform you of it. Like CVS, only the committed
files will be updated: you will need run <tt>cvs up</tt> to update the rest of the
files.

If you want to retrieve a specific revision of a file, you can use the <tt>-r</tt>
switch. Besides the revision number itself, -r accepts a number of other
possibilities:

* The revision number: for example, use -r 403819 to retrieve that version
* '''BASE''': the revision you updated to
* '''COMMITTED''': the revision a file was last modified, before BASE
* '''PREV''': the revision of the previous commit to the file before COMMITTED
* '''HEAD''': the most recent revision available in the server
* '''{ date }''': between curly brackets, you can specify a date for searching the closest revisions

The following illustrates the evolution of the keywords:

# You run <tt>svn up</tt> to update to the latest available revision. Suppose Subversion tells you it updated to revision 403821. This means that HEAD and BASE are 403821.
# You modify file README and commit it. Suppose Subversion tells you it committed revision 403822. This means HEAD, BASE and COMMITTED are 403822.
# You modify the file again and commit it. Now PREV is 403822, but HEAD, BASE and COMMITTED are updated to a new value (suppose it's 403823).
# Now someone else modifies the repository, and you update your working copy. If Subversion tells you it updated to 403824, this means now HEAD and BASE are moved to 403824 (but PREV and COMMITTED stay the same)
# If someone modifies the README file now, HEAD is moved. The other keywords stay the same for you, until you update. At this time, we will have HEAD = 403825 (the latest available revision), BASE = 403824 (the revision you last updated to), COMMITTED = 403823 (the revision of the latest change to the file when you last updated) and PREV = 403822 (the revision of the change before COMMITTED)

Those keywords are useful to retrieve logs and diffs for commits to the
repository.

If you want to see the difference between your working copy and BASE, you
can run:

svn diff

This is a very fast operation, since Subversion keeps a local copy of BASE.
It doesn't need a network connection to accomplish this operation.

If you want to see the difference between your local copy and the latest
available on the server, you will run:

svn diff -r HEAD

If you want to see what has changed in the repository since you've last updated, you can use:
svn diff -r BASE:HEAD

If you want to see the last change to a file before BASE, you can use:
svn diff -r PREV:BASE
# or
svn diff -r PREV:COMMITTED

That is also valid for the <tt>svn log</tt> command.

== Unterverzeichnisse von anderen Orten verlinken ==

It can happen you would like to include a copy of a subdirectory from another place, but just for convenience, not for developing the code in there. Of course it should be updated automatically whenever the original changes. Subversion can help you. You need to edit the property <tt>svn:external</tt> of the directory the subdirectory should be added to. So for the current directory you use
svn propedit svn:externals .
and then enter lines of the form
libkhalkhi svn://anonsvn.kde.org/home/kde/trunk/playground/pim/khalkhi
Updating will now fetch <tt>/trunk/playground/pim/khalkhi</tt> into the subdirectoy <tt>libkhalkhi</tt>.

{{warning (de)|Beware that you cannot commit changes you did to the local copy of the external subdirectory, it is just a readonly copy.}}

You use <tt>svn://anonsvn.kde.org</tt> and not another protocol, because <tt>anonsvn.kde.org</tt> is accessible to everyone. Using <tt>https:</tt> or <tt>svn+ssh:</tt> would only work for users of that protocol. There are still some small disadvantage with <tt>anonsvn.kde.org</tt>: It is not always in synchronization with <tt>svn.kde.org</tt>, so updates in the original branch may take a while to appear on <tt>anonsvn.kde.org</tt>. And some strict firewalls are blocking the <tt>svn:</tt> protocol.

A special case in KDE 3 is the subdirectory <tt>admin</tt>, containing the KDE 3 build utilities. It is linked in to the top directory in all modules, and maintained in <tt>/branches/KDE/3.5/kde-common</tt>. For <tt>admin</tt> the KDE subversion server is configured to allow readonly access for everyone, so if you see
admin https://svn.kde.org/home/kde/branches/KDE/3.5/kde-common/admin
there is no need to change this.

== Mehr Informationen im KDE Wiki ==

Siehe auch [http://wiki.kde.org/tiki-index.php?page=KDE%20Subversion%20HOWTO the KDE wiki] für mehr Informationen über Subversion in KDE

Getting Started/Sources/Subversion (de)

2008-01-19T06:43:09Z

DrSlowDecay: /* Zusammenfassung */ Typo

{{Template:I18n/Language Navigation Bar|Getting Started/Sources/Using Subversion with KDE}}

{{TutorialBrowser (de)|

series=Anfang|

name=Subversion mit KDE benutzen|
}}

== Zusammenfassung ==

Der folgende Text ist eine schnelle kde-spezifische Einführung, wie man Subversion benutzt, um auf Dateien und Software im KDE Repository zuzugreifen. Für einen vollständigen Überblick über die Fähigkeiten von Subversion verweisen wir auf das Buch "[http://svnbook.red-bean.com/ Version Control with Subversion (englisch)]".

== Am Anfang ==

In order to use the KDE Subversion repository, you will need two things:

# A Subversion client program
# An account in our repository

Note: For anonymous read-only access use protocol "svn", no "yourname@" and server "anonsvn.kde.org" instead below.

'''Installing Subversion:''' instructions on installing the client are not
presented here. Refer to your system installation instructions to find out how
you can install Subversion. You will need version 1.1 at least. If you are
compiling from sources and want to access the KDE repository by https
(and not by svn+ssh), you will need SSL and ZLIB support,
so you will need the <tt>--with-ssl --with-zlib</tt> options.

Alternatively, you can install one of the many graphical clients out there.
This tutorial is intended for people using the <tt>svn</tt> program only, referring
to tasks accomplished with the usual <tt>cvs</tt> program.

'''Getting an account:''' if you had a CVS
account before, it has been migrated to the new Subversion client. If
you didn't, refer to the [[Contribute/Get_a_SVN_Account|corresponding tutorial]] how to get one.

{{Note (de)|If you have lost your CVS password, there are simple ways to retrieve
it. Use [http://ktown.kde.org/~coolo/cvspwd.c cvspwd.c] or [http://kdab.net/~dfaure/cvs-unscramble cvs-unscramble] (Perl).}}

== Die Struktur des KDE Repository ==

svn.kde.org/home/kde

That's the address of the KDE Subversion repository. The repository is served by
HTTPS or SVN+SSH protocol, which means your password is secure against third-party
eavesdropping.

The SSL certificate md5 fingerprint for the repositories:
F6BF EDE2 D016 D1B2 4F18 742E 2C8F B7EF

The SSL certificate sha1 fingerprint for the repositories:
e1:e6:41:96:3c:eb:ae:78:e2:73:0d:a2:32:2f:6b:21:13:bf:3d:0f

For people using svn+ssh, here's the fingerprint of the server's RSA key:
86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb

The repository is organised in main directories:

# /branches
# /tags
# /trunk

You can explore the repository structure at [http://websvn.kde.org/ http://websvn.kde.org/]

=== Das Unterverzeichnis /trunk ===

The <tt>/trunk</tt>
top-level subdirectory is where the main development for KDE occurs.
What you will find here is what will become the next KDE release, and
its associated programs. Here you will also find the <tt>www</tt> module,
which contains webpages for KDE's site and related ones.

<tt>/trunk</tt> is further subdivided into these sub-directories:

*<tt>KDE/</tt> KDE itself, what will become the next public release. It contains the following modules:
**'''kdelibs''' - KDE basic libraries, used by all KDE programs
**'''kdebase''' - KDE base programs, like the KDE Control Center, Kicker (the panel) and Konqueror (the web browser)
**'''kdeaccessibility''' - Accessibility files
**'''kdeadmin''' - KDE Administration applications
**'''kdeartwork''' - Images, themes, sounds and other art files
**'''kdebindings''' - Bindings for languages other than C++
**'''kdeedu''' - KDE Educational applications
**'''kdegames''' - KDE Games
**'''kdegraphics''' - KDE Graphical applications
**'''kdemultimedia''' - KDE Multimedia applications
**'''kdenetwork''' - KDE Networking applications
**'''kdepim''' - KDE Personal Information Management applications
**'''kdepimlibs''' - Libraries used by KDE-PIM applications.
**'''kdesdk''' - KDE Software Development Kit applications
**'''kdetoys''' - KDE toy applications
**'''kdeutils''' - KDE General utilities
**'''kdevelop''' - The KDevelop program
**'''kdevplatform''' - The development platform which KDevelop is based on
**'''kdewebdev''' - KDE Web development applications
*<tt>kde-common</tt>
:Common admin/ directory
*<tt>bugs/</tt>
:[http://bugs.kde.org/ Bugzilla] files
*<tt>developer.kde.org/</tt>
:The content of developer.kde.org
*<tt>extragear/</tt>
:KDE programs outside the main KDE releases.
*<tt>kdereview/</tt>
:Temporary home for KDE applications that are believed to have reached release-quality. From here, once all major issues are resolved, applications are moved either to <tt>/trunk/KDE/</tt> or to <tt>/trunk/extragear/</tt>
*<tt>kdesupport/</tt>
:Supporting applications and libraries for KDE
*<tt>koffice/</tt> The KDE Office suite, containing the programs:
**'''karbon'''
**'''kchart'''
**'''kexi'''
**'''kformula'''
**'''kivio'''
**'''koshell'''
**'''kplato'''
**'''kpresenter'''
**'''krita'''
**'''kspread'''
**'''kugar'''
**'''kword'''
*<tt>konstruct/</tt>
:Konstruct, the KDE build program
*<tt>l10n-kde3/</tt>
:Translations for the "unstable" modules of KDE 3 (extragear, playground)
*<tt>l10n-kde4/</tt>
:Translations for KDE 4
*<tt>playground/</tt>
:The KDE playground: applications being developed, but not having yet reached release-quality.
*<tt>qt-copy/</tt>
:The convenience copy of [http://www.trolltech.com/ Trolltech's] Qt library, which KDE is based upon.
*<tt>tests/</tt>
:khtml, KOffice and ksvg testcases
*<tt>valgrind/</tt>
:The Valgrind application, which is hosted on the KDE repository, but that is not part of KDE itself. Note that newer versions of Valgrind are developed on their own repository. The KDE Valgrind modules only holds up to Valgrind 2.4.
*<tt>www/</tt>
:Webpages for the KDE site (and related sites). Write access to this directory is restricted.

=== Das Unterverzeichnis <tt>/tags</tt> ===

This
directory contains the official releases of the programs maintained and
developed in the KDE repository. Each individual application has a
subdirectory here. Inside it, you will find the release numbers.

For instance, the KDE 3.4.0 code can be found under <tt>/tags/KDE/3.4.0/</tt>.

=== Das Unterverzeichnis <tt>/branches</tt> ===

This directory contains the branch versions of the applications after a major release.

Most
KDE applications adhere to the philosphy that new features (as well as
new user-visible strings) are added only to the next release cycle —
the one that lives in <tt>/trunk/</tt>. However, bugfixes are applied to all
applications, even after release.

In
order to do that, a branch is created at the moment of the release,
indicating the state of the files at that time. Bugfixes are then
checked in to those files. Those branches are the ones in <tt>/branches/</tt>.

For instance, the KDE 3.4.x branch can be found under <tt>/branches/KDE/3.4/</tt>

The subdirectories you will find inside <tt>/branches</tt> are the
application subdirs, like <tt>akregator/</tt>, <tt>amarok/</tt>,
<tt>arts/</tt>, <tt>k3b/</tt>, etc. You will also find a <tt>KDE/</tt>
subdir, containing the official KDE releases since time immemorial.

One special subdir is found in <tt>/branches</tt>: <tt>work/</tt>. This
subdir contains the so-called "work branches", that is, branches containing
features being worked on, sometimes highly experimental. Multi-application
work branches always are checked in to <tt>/branches/work/</tt>, but
single-application branches may be found in each application's subdir. That
is a decision left to the developers.

== Auschecken und Aktualisieren ==

=== Auschecken ===
In order to check out something with Subversion, you use the <tt>checkout</tt> subcommand.

'''WARNING:''' If you checkout trunk/KDE/ or branches/KDE/foo/ you will download complete kde-i18n!

Suppose you wanted to check out only KDevelop from the KDE repository. You would do:

CVS command:
cvs -d :pserver:yourname@cvs.kde.org:/home/kde login
cvs -d :pserver:yourname@cvs.kde.org:/home/kde checkout kdevelop

Subversion command:

CVS users currently using ssh access, should use protocol svn+ssh,
CVS users currently using password access, should use protocol https
in the following.

svn checkout <protocol>://<username>@svn.kde.org/home/kde/trunk/KDE/kdevelop

=== Aktualisieren ===

In order to update, you use the <tt>update</tt> subcommand.

This is no different from CVS: you change into your checked out copy (for those new to this whole process, the checked out copy should be in your Home folder) and issue a <tt>svn update</tt> (or, shorter, <tt>svn up</tt>) command.

== Den Status einer Datei ermitteln ==

To know which local files you had modified, in CVS most people did
cvs up
and looked at the files with '''M''', this does not work with svn so you have to do
svn status
to know the status of the files.

== Ins Repository hochladen ==

Just like in CVS, committing to the Subversion repository is accomplished
with the <tt>commit</tt> or <tt>checkin</tt> (<tt>ci</tt> for short) subcommands.

CVS command:
cvs commit
# or
cvs ci
# or
cvs ci filename.cpp

Subversion command:
svn commit
# or
svn ci
# or
svn ci filename.cpp

This way, <tt>svn</tt> will launch the editor specified in <tt>$SVN_EDITOR</tt> for you
to compose the commit message. If you prefer, you can give <tt>svn</tt> the -m
oprtion with your full message:

svn ci -m "Updating protocol to conform to HTTP/1.1"

== Dateien ignorieren ==

Subversion stores ignored files per directory. To edit the ignored
files of the directory you are currently in, do
svn propedit svn:ignore .
that will launch your editor, write there the names of the files you want to
ignore, one file per line. Once you are done, do a commit so the ignored list
file gets updated on the server.

A lot of files were ignored in CVS with help from global ignore list which
is not supported yet by SVN. You can wait for svn 1.3 or you need to add the
ignore list to the [miscellany] group in your {{path|~/.subversion/config}} (all in
one line):

global-ignores = *.o *.lo *.la .*.rej *.rej .*~ *~ .#* #*# .DS_Store *.moc
*.moc.cc *.moc.cpp config.log config.status config.cache *.gmo .deps .libs
SunWS_cache *.lo *.la *.rpo *.la.closure *_la_closure.cpp *_la_closure.cc
*_la_closure.cxx *.all_cc.cc *.all_cpp.cpp *.all_C.C *.all_cxx.cxx
*_meta_unload.cc *_meta_unload.h *_meta_unload.cpp *_meta_unload.C
*_meta_unload.cxx index.cache.bz2 .memdump Makefile.rules.in Makefile.calls.in
Makefile.rules Makefile.calls autom4te.cache *.kidl

== Working with multiple revisions and branches ==

Unlike CVS, Subversion doesn't generate a revision number for each file
modified. Instead, the full repository is versioned, as a whole. This way, a
given revision number represents the state the repository was on a given date.
In other words, a revision number is like a timestamp (in fact, the Subversion
server uses this fact to search for dates in the repository faster).

So, for instance, when you check out the KDE repository, Subversion will
tell you the following:

Updated to revision 403821.

This means that the latest revision available at the time of the operation
was 403821. If you make a modification and commit, Subversion will update the
server-side revision and will inform you of it. Like CVS, only the committed
files will be updated: you will need run <tt>cvs up</tt> to update the rest of the
files.

If you want to retrieve a specific revision of a file, you can use the <tt>-r</tt>
switch. Besides the revision number itself, -r accepts a number of other
possibilities:

* The revision number: for example, use -r 403819 to retrieve that version
* '''BASE''': the revision you updated to
* '''COMMITTED''': the revision a file was last modified, before BASE
* '''PREV''': the revision of the previous commit to the file before COMMITTED
* '''HEAD''': the most recent revision available in the server
* '''{ date }''': between curly brackets, you can specify a date for searching the closest revisions

The following illustrates the evolution of the keywords:

# You run <tt>svn up</tt> to update to the latest available revision. Suppose Subversion tells you it updated to revision 403821. This means that HEAD and BASE are 403821.
# You modify file README and commit it. Suppose Subversion tells you it committed revision 403822. This means HEAD, BASE and COMMITTED are 403822.
# You modify the file again and commit it. Now PREV is 403822, but HEAD, BASE and COMMITTED are updated to a new value (suppose it's 403823).
# Now someone else modifies the repository, and you update your working copy. If Subversion tells you it updated to 403824, this means now HEAD and BASE are moved to 403824 (but PREV and COMMITTED stay the same)
# If someone modifies the README file now, HEAD is moved. The other keywords stay the same for you, until you update. At this time, we will have HEAD = 403825 (the latest available revision), BASE = 403824 (the revision you last updated to), COMMITTED = 403823 (the revision of the latest change to the file when you last updated) and PREV = 403822 (the revision of the change before COMMITTED)

Those keywords are useful to retrieve logs and diffs for commits to the
repository.

If you want to see the difference between your working copy and BASE, you
can run:

svn diff

This is a very fast operation, since Subversion keeps a local copy of BASE.
It doesn't need a network connection to accomplish this operation.

If you want to see the difference between your local copy and the latest
available on the server, you will run:

svn diff -r HEAD

If you want to see what has changed in the repository since you've last updated, you can use:
svn diff -r BASE:HEAD

If you want to see the last change to a file before BASE, you can use:
svn diff -r PREV:BASE
# or
svn diff -r PREV:COMMITTED

That is also valid for the <tt>svn log</tt> command.

== Unterverzeichnisse von anderen Orten verlinken ==

It can happen you would like to include a copy of a subdirectory from another place, but just for convenience, not for developing the code in there. Of course it should be updated automatically whenever the original changes. Subversion can help you. You need to edit the property <tt>svn:external</tt> of the directory the subdirectory should be added to. So for the current directory you use
svn propedit svn:externals .
and then enter lines of the form
libkhalkhi svn://anonsvn.kde.org/home/kde/trunk/playground/pim/khalkhi
Updating will now fetch <tt>/trunk/playground/pim/khalkhi</tt> into the subdirectoy <tt>libkhalkhi</tt>.

{{warning (de)|Beware that you cannot commit changes you did to the local copy of the external subdirectory, it is just a readonly copy.}}

You use <tt>svn://anonsvn.kde.org</tt> and not another protocol, because <tt>anonsvn.kde.org</tt> is accessible to everyone. Using <tt>https:</tt> or <tt>svn+ssh:</tt> would only work for users of that protocol. There are still some small disadvantage with <tt>anonsvn.kde.org</tt>: It is not always in synchronization with <tt>svn.kde.org</tt>, so updates in the original branch may take a while to appear on <tt>anonsvn.kde.org</tt>. And some strict firewalls are blocking the <tt>svn:</tt> protocol.

A special case in KDE 3 is the subdirectory <tt>admin</tt>, containing the KDE 3 build utilities. It is linked in to the top directory in all modules, and maintained in <tt>/branches/KDE/3.5/kde-common</tt>. For <tt>admin</tt> the KDE subversion server is configured to allow readonly access for everyone, so if you see
admin https://svn.kde.org/home/kde/branches/KDE/3.5/kde-common/admin
there is no need to change this.

== Mehr Informationen im KDE Wiki ==

See [http://wiki.kde.org/tiki-index.php?page=KDE%20Subversion%20HOWTO the KDE wiki] for more
information about subversion in KDE

Getting Started/Sources/Subversion (de)

2008-01-18T16:41:53Z

DrSlowDecay: /* Zusammenfassung */ Translated

{{Template:I18n/Language Navigation Bar|Getting Started/Sources/Using Subversion with KDE}}

{{TutorialBrowser (de)|

series=Anfang|

name=Subversion mit KDE benutzen|
}}

== Zusammenfassung ==

Der folgende Text ist eine schnelle kde-spezifische Einführung, wie man Subversion benutzt um auf Dateien und Software im KDE Repository zugreift. Für einen vollständigen Überblick über die Fähigkeiten von Subversion verweisen wir auf das Buch "[http://svnbook.red-bean.com/ Version Control with Subversion (englisch)]".

== Am Anfang ==

In order to use the KDE Subversion repository, you will need two things:

# A Subversion client program
# An account in our repository

Note: For anonymous read-only access use protocol "svn", no "yourname@" and server "anonsvn.kde.org" instead below.

'''Installing Subversion:''' instructions on installing the client are not
presented here. Refer to your system installation instructions to find out how
you can install Subversion. You will need version 1.1 at least. If you are
compiling from sources and want to access the KDE repository by https
(and not by svn+ssh), you will need SSL and ZLIB support,
so you will need the <tt>--with-ssl --with-zlib</tt> options.

Alternatively, you can install one of the many graphical clients out there.
This tutorial is intended for people using the <tt>svn</tt> program only, referring
to tasks accomplished with the usual <tt>cvs</tt> program.

'''Getting an account:''' if you had a CVS
account before, it has been migrated to the new Subversion client. If
you didn't, refer to the [[Contribute/Get_a_SVN_Account|corresponding tutorial]] how to get one.

{{Note (de)|If you have lost your CVS password, there are simple ways to retrieve
it. Use [http://ktown.kde.org/~coolo/cvspwd.c cvspwd.c] or [http://kdab.net/~dfaure/cvs-unscramble cvs-unscramble] (Perl).}}

== Die Struktur des KDE Repository ==

svn.kde.org/home/kde

That's the address of the KDE Subversion repository. The repository is served by
HTTPS or SVN+SSH protocol, which means your password is secure against third-party
eavesdropping.

The SSL certificate md5 fingerprint for the repositories:
F6BF EDE2 D016 D1B2 4F18 742E 2C8F B7EF

The SSL certificate sha1 fingerprint for the repositories:
e1:e6:41:96:3c:eb:ae:78:e2:73:0d:a2:32:2f:6b:21:13:bf:3d:0f

For people using svn+ssh, here's the fingerprint of the server's RSA key:
86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb

The repository is organised in main directories:

# /branches
# /tags
# /trunk

You can explore the repository structure at [http://websvn.kde.org/ http://websvn.kde.org/]

=== Das Unterverzeichnis /trunk ===

The <tt>/trunk</tt>
top-level subdirectory is where the main development for KDE occurs.
What you will find here is what will become the next KDE release, and
its associated programs. Here you will also find the <tt>www</tt> module,
which contains webpages for KDE's site and related ones.

<tt>/trunk</tt> is further subdivided into these sub-directories:

*<tt>KDE/</tt> KDE itself, what will become the next public release. It contains the following modules:
**'''kdelibs''' - KDE basic libraries, used by all KDE programs
**'''kdebase''' - KDE base programs, like the KDE Control Center, Kicker (the panel) and Konqueror (the web browser)
**'''kdeaccessibility''' - Accessibility files
**'''kdeadmin''' - KDE Administration applications
**'''kdeartwork''' - Images, themes, sounds and other art files
**'''kdebindings''' - Bindings for languages other than C++
**'''kdeedu''' - KDE Educational applications
**'''kdegames''' - KDE Games
**'''kdegraphics''' - KDE Graphical applications
**'''kdemultimedia''' - KDE Multimedia applications
**'''kdenetwork''' - KDE Networking applications
**'''kdepim''' - KDE Personal Information Management applications
**'''kdepimlibs''' - Libraries used by KDE-PIM applications.
**'''kdesdk''' - KDE Software Development Kit applications
**'''kdetoys''' - KDE toy applications
**'''kdeutils''' - KDE General utilities
**'''kdevelop''' - The KDevelop program
**'''kdevplatform''' - The development platform which KDevelop is based on
**'''kdewebdev''' - KDE Web development applications
*<tt>kde-common</tt>
:Common admin/ directory
*<tt>bugs/</tt>
:[http://bugs.kde.org/ Bugzilla] files
*<tt>developer.kde.org/</tt>
:The content of developer.kde.org
*<tt>extragear/</tt>
:KDE programs outside the main KDE releases.
*<tt>kdereview/</tt>
:Temporary home for KDE applications that are believed to have reached release-quality. From here, once all major issues are resolved, applications are moved either to <tt>/trunk/KDE/</tt> or to <tt>/trunk/extragear/</tt>
*<tt>kdesupport/</tt>
:Supporting applications and libraries for KDE
*<tt>koffice/</tt> The KDE Office suite, containing the programs:
**'''karbon'''
**'''kchart'''
**'''kexi'''
**'''kformula'''
**'''kivio'''
**'''koshell'''
**'''kplato'''
**'''kpresenter'''
**'''krita'''
**'''kspread'''
**'''kugar'''
**'''kword'''
*<tt>konstruct/</tt>
:Konstruct, the KDE build program
*<tt>l10n-kde3/</tt>
:Translations for the "unstable" modules of KDE 3 (extragear, playground)
*<tt>l10n-kde4/</tt>
:Translations for KDE 4
*<tt>playground/</tt>
:The KDE playground: applications being developed, but not having yet reached release-quality.
*<tt>qt-copy/</tt>
:The convenience copy of [http://www.trolltech.com/ Trolltech's] Qt library, which KDE is based upon.
*<tt>tests/</tt>
:khtml, KOffice and ksvg testcases
*<tt>valgrind/</tt>
:The Valgrind application, which is hosted on the KDE repository, but that is not part of KDE itself. Note that newer versions of Valgrind are developed on their own repository. The KDE Valgrind modules only holds up to Valgrind 2.4.
*<tt>www/</tt>
:Webpages for the KDE site (and related sites). Write access to this directory is restricted.

=== Das Unterverzeichnis <tt>/tags</tt> ===

This
directory contains the official releases of the programs maintained and
developed in the KDE repository. Each individual application has a
subdirectory here. Inside it, you will find the release numbers.

For instance, the KDE 3.4.0 code can be found under <tt>/tags/KDE/3.4.0/</tt>.

=== Das Unterverzeichnis <tt>/branches</tt> ===

This directory contains the branch versions of the applications after a major release.

Most
KDE applications adhere to the philosphy that new features (as well as
new user-visible strings) are added only to the next release cycle —
the one that lives in <tt>/trunk/</tt>. However, bugfixes are applied to all
applications, even after release.

In
order to do that, a branch is created at the moment of the release,
indicating the state of the files at that time. Bugfixes are then
checked in to those files. Those branches are the ones in <tt>/branches/</tt>.

For instance, the KDE 3.4.x branch can be found under <tt>/branches/KDE/3.4/</tt>

The subdirectories you will find inside <tt>/branches</tt> are the
application subdirs, like <tt>akregator/</tt>, <tt>amarok/</tt>,
<tt>arts/</tt>, <tt>k3b/</tt>, etc. You will also find a <tt>KDE/</tt>
subdir, containing the official KDE releases since time immemorial.

One special subdir is found in <tt>/branches</tt>: <tt>work/</tt>. This
subdir contains the so-called "work branches", that is, branches containing
features being worked on, sometimes highly experimental. Multi-application
work branches always are checked in to <tt>/branches/work/</tt>, but
single-application branches may be found in each application's subdir. That
is a decision left to the developers.

== Auschecken und Aktualisieren ==

=== Auschecken ===
In order to check out something with Subversion, you use the <tt>checkout</tt> subcommand.

'''WARNING:''' If you checkout trunk/KDE/ or branches/KDE/foo/ you will download complete kde-i18n!

Suppose you wanted to check out only KDevelop from the KDE repository. You would do:

CVS command:
cvs -d :pserver:yourname@cvs.kde.org:/home/kde login
cvs -d :pserver:yourname@cvs.kde.org:/home/kde checkout kdevelop

Subversion command:

CVS users currently using ssh access, should use protocol svn+ssh,
CVS users currently using password access, should use protocol https
in the following.

svn checkout <protocol>://<username>@svn.kde.org/home/kde/trunk/KDE/kdevelop

=== Aktualisieren ===

In order to update, you use the <tt>update</tt> subcommand.

This is no different from CVS: you change into your checked out copy (for those new to this whole process, the checked out copy should be in your Home folder) and issue a <tt>svn update</tt> (or, shorter, <tt>svn up</tt>) command.

== Den Status einer Datei ermitteln ==

To know which local files you had modified, in CVS most people did
cvs up
and looked at the files with '''M''', this does not work with svn so you have to do
svn status
to know the status of the files.

== Ins Repository hochladen ==

Just like in CVS, committing to the Subversion repository is accomplished
with the <tt>commit</tt> or <tt>checkin</tt> (<tt>ci</tt> for short) subcommands.

CVS command:
cvs commit
# or
cvs ci
# or
cvs ci filename.cpp

Subversion command:
svn commit
# or
svn ci
# or
svn ci filename.cpp

This way, <tt>svn</tt> will launch the editor specified in <tt>$SVN_EDITOR</tt> for you
to compose the commit message. If you prefer, you can give <tt>svn</tt> the -m
oprtion with your full message:

svn ci -m "Updating protocol to conform to HTTP/1.1"

== Dateien ignorieren ==

Subversion stores ignored files per directory. To edit the ignored
files of the directory you are currently in, do
svn propedit svn:ignore .
that will launch your editor, write there the names of the files you want to
ignore, one file per line. Once you are done, do a commit so the ignored list
file gets updated on the server.

A lot of files were ignored in CVS with help from global ignore list which
is not supported yet by SVN. You can wait for svn 1.3 or you need to add the
ignore list to the [miscellany] group in your {{path|~/.subversion/config}} (all in
one line):

global-ignores = *.o *.lo *.la .*.rej *.rej .*~ *~ .#* #*# .DS_Store *.moc
*.moc.cc *.moc.cpp config.log config.status config.cache *.gmo .deps .libs
SunWS_cache *.lo *.la *.rpo *.la.closure *_la_closure.cpp *_la_closure.cc
*_la_closure.cxx *.all_cc.cc *.all_cpp.cpp *.all_C.C *.all_cxx.cxx
*_meta_unload.cc *_meta_unload.h *_meta_unload.cpp *_meta_unload.C
*_meta_unload.cxx index.cache.bz2 .memdump Makefile.rules.in Makefile.calls.in
Makefile.rules Makefile.calls autom4te.cache *.kidl

== Working with multiple revisions and branches ==

Unlike CVS, Subversion doesn't generate a revision number for each file
modified. Instead, the full repository is versioned, as a whole. This way, a
given revision number represents the state the repository was on a given date.
In other words, a revision number is like a timestamp (in fact, the Subversion
server uses this fact to search for dates in the repository faster).

So, for instance, when you check out the KDE repository, Subversion will
tell you the following:

Updated to revision 403821.

This means that the latest revision available at the time of the operation
was 403821. If you make a modification and commit, Subversion will update the
server-side revision and will inform you of it. Like CVS, only the committed
files will be updated: you will need run <tt>cvs up</tt> to update the rest of the
files.

If you want to retrieve a specific revision of a file, you can use the <tt>-r</tt>
switch. Besides the revision number itself, -r accepts a number of other
possibilities:

* The revision number: for example, use -r 403819 to retrieve that version
* '''BASE''': the revision you updated to
* '''COMMITTED''': the revision a file was last modified, before BASE
* '''PREV''': the revision of the previous commit to the file before COMMITTED
* '''HEAD''': the most recent revision available in the server
* '''{ date }''': between curly brackets, you can specify a date for searching the closest revisions

The following illustrates the evolution of the keywords:

# You run <tt>svn up</tt> to update to the latest available revision. Suppose Subversion tells you it updated to revision 403821. This means that HEAD and BASE are 403821.
# You modify file README and commit it. Suppose Subversion tells you it committed revision 403822. This means HEAD, BASE and COMMITTED are 403822.
# You modify the file again and commit it. Now PREV is 403822, but HEAD, BASE and COMMITTED are updated to a new value (suppose it's 403823).
# Now someone else modifies the repository, and you update your working copy. If Subversion tells you it updated to 403824, this means now HEAD and BASE are moved to 403824 (but PREV and COMMITTED stay the same)
# If someone modifies the README file now, HEAD is moved. The other keywords stay the same for you, until you update. At this time, we will have HEAD = 403825 (the latest available revision), BASE = 403824 (the revision you last updated to), COMMITTED = 403823 (the revision of the latest change to the file when you last updated) and PREV = 403822 (the revision of the change before COMMITTED)

Those keywords are useful to retrieve logs and diffs for commits to the
repository.

If you want to see the difference between your working copy and BASE, you
can run:

svn diff

This is a very fast operation, since Subversion keeps a local copy of BASE.
It doesn't need a network connection to accomplish this operation.

If you want to see the difference between your local copy and the latest
available on the server, you will run:

svn diff -r HEAD

If you want to see what has changed in the repository since you've last updated, you can use:
svn diff -r BASE:HEAD

If you want to see the last change to a file before BASE, you can use:
svn diff -r PREV:BASE
# or
svn diff -r PREV:COMMITTED

That is also valid for the <tt>svn log</tt> command.

== Unterverzeichnisse von anderen Orten verlinken ==

It can happen you would like to include a copy of a subdirectory from another place, but just for convenience, not for developing the code in there. Of course it should be updated automatically whenever the original changes. Subversion can help you. You need to edit the property <tt>svn:external</tt> of the directory the subdirectory should be added to. So for the current directory you use
svn propedit svn:externals .
and then enter lines of the form
libkhalkhi svn://anonsvn.kde.org/home/kde/trunk/playground/pim/khalkhi
Updating will now fetch <tt>/trunk/playground/pim/khalkhi</tt> into the subdirectoy <tt>libkhalkhi</tt>.

{{warning (de)|Beware that you cannot commit changes you did to the local copy of the external subdirectory, it is just a readonly copy.}}

You use <tt>svn://anonsvn.kde.org</tt> and not another protocol, because <tt>anonsvn.kde.org</tt> is accessible to everyone. Using <tt>https:</tt> or <tt>svn+ssh:</tt> would only work for users of that protocol. There are still some small disadvantage with <tt>anonsvn.kde.org</tt>: It is not always in synchronization with <tt>svn.kde.org</tt>, so updates in the original branch may take a while to appear on <tt>anonsvn.kde.org</tt>. And some strict firewalls are blocking the <tt>svn:</tt> protocol.

A special case in KDE 3 is the subdirectory <tt>admin</tt>, containing the KDE 3 build utilities. It is linked in to the top directory in all modules, and maintained in <tt>/branches/KDE/3.5/kde-common</tt>. For <tt>admin</tt> the KDE subversion server is configured to allow readonly access for everyone, so if you see
admin https://svn.kde.org/home/kde/branches/KDE/3.5/kde-common/admin
there is no need to change this.

== Mehr Informationen im KDE Wiki ==

See [http://wiki.kde.org/tiki-index.php?page=KDE%20Subversion%20HOWTO the KDE wiki] for more
information about subversion in KDE

Development/Architecture (de)

2008-01-18T16:39:22Z

DrSlowDecay: /* Design Dokumente */ Translated titles

{{Template:I18n/Language Navigation Bar|Development/Architecture}}
Die folgenden Seiten beinhalten detailierte Dokumentationen über das Design und die Architektur von KDE. Sie ersetzen nicht die anderen Dokumentationen wie [http://api.kde.org API Dokumentation (englisch)], [[../Tutorials|tutorials/howtos]] und [[../Guidelines|standards]], siehe auch das [[Development (de)|Entwickler Portal]] für weitere Informationen.

Für ein besseren Verständnis könnte es helfen sich mit Trolltech's™ excellenter [http://doc.trolltech.com/3.3/index.html Qt 3.3] oder [http://doc.trolltech.com/4.3/index.html Qt 4.3] Dokumentation und deren [http://www.trolltech.com/developer/ Entwickler Seiten] zu beschäftigen.

Für mehr Informationen über eine KDE Installtion sehen Sie bitte auch die entsprechenden Kapitel in [[KDE System Administration|System Administration]].

== Design Dokumente ==
; [[Development/Architecture/KDE4|Überblick über die KDE 4 Architektur]]
: Ein Überblick über die KDE 4 Architektur einschließlich Diskussionen über allgemeine Techniken, Bibliotheksklassen und allgemeine Entwicklerfragen. Gilt für ''KDE 4.0''.

; [[Development/Architecture/KDE3|Überblick über die KDE 3 Architektur]] [http://developer.kde.org/documentation/library/kdeqt/kde3arch/ (Original)]
: Ein Überblick über die KDE 3 Architektur einschließlich Diskussionen über allgemeine Techniken, Bibliotheksklassen und allgemeine Entwicklerfragen. Gilt für ''KDE 3.0''.

; [http://developer.kde.org/documentation/library/kdeqt/kde2arch/ Überblick über die KDE 2 Architektur]
: Ein Überblick über die KDE 2 Architektur einschließlich Diskussionen über allgemeine Techniken, Bibliotheksklassen und allgemeine Entwicklerfragen. Gilt für ''KDE 2.2''.

; [[Development/Architecture/DCOP|DCOP]]
: Design Dokumente von 1999-2000.

[[Category:Architecture]]

Contribute (de)

2008-01-18T16:35:03Z

DrSlowDecay: /* Neuigkeiten und Post Quellen */ Changed translation

{{Template:I18n/Language Navigation Bar|Contribute}}
Diese Seite versucht einen Überblick über die verschiedenen Aspekte der KDE-Entwicklung, insbesondere der Programmierung zu bieten. '''Das KDE-Projekt heißt jeden willkommen der helfen möchte'''.

{{note|Es gibt viele Wege um sich in der KDE-Entwicklung zu engagieren, welche in folgende Kategorien gegliedert werden können:
:''Dokumentation, Übersetzung, Entwicklung, Benutzerfreundlichkeit, Barrierefreiheit, Künstlerische Arbeit, Vermarktung
'''Besonders für Aufgaben neben der Entwicklung (Programmierung) geben die KDE-Seiten [http://kde.org/getinvolved/ wie man sich beteiligt] einen guten Überblick.'''
}}

== Neuigkeiten und eMail Quellen ==
Die generelle Richtung des KDE-Projektes wird von denen bestimmt, die die Arbeit machen - es existiert kein übergeordneter Plan der festlegt wie KDE in der Zukunft aussehen soll.

Wenn Sie sich über das gegenwärtige Geschehen informieren möchten, können sie folgende Quellen nutzen:
; [http://www.kde.org/mailinglists/ Mailinglisten]
: Wahrscheinlich der beste Weg um herauszufinden was sich in der KDE-Entwicklung ereignet. Archive sind [http://lists.kde.org hier] verfügbar.

; [http://commitfilter.kde.org/ CommitFilter]
: Hier erhalten Sie Benachrichtigungen über [http://de.wikipedia.org/wiki/Subversion_(Software) SVN]-Transaktionen die Sie interessieren.

; [http://commit-digest.org/ KDE Commit-Digest]
: Eine wöchentliche Zusammenfassung der SVN-Transaktionen.

; [http://dot.kde.org/ The Dot]
: Die KDE-Nachrichtenseite.

== Mit dem Programmieren beginnen ==
Mit dem Programmieren beginnen heißt, etwas zum Ausbessern zu finden und es auszubessern. Um zu finden was Sie suchen, können Sie die Modul-Übersicht zur Hilfe nehmen. Sobald Sie etwas ausgebessert haben, können Sie einen Patch zuschicken. Nachdem Sie es einige Male gemacht haben, können Sie einen SVN-Account beantragen, so dass Sie die Dinge direkt verändern können.
* [[Contribute/List of KDE Modules|Modul-Übersicht]]
* [[Contribute/Send Patches|Patches zuschicken]]
* [[Contribute/Get a SVN Account|Einen KDE-SVN-Account beantragen]]
* [[Contribute/First Steps with your KDE SVN Account|Erste Schritte mit Ihren neuen SVN-Account]]

Gegenwärtig existieren zwei Möglichkeiten der KDE-Entwicklung - Sie können an KDE 3 oder KDE 4 arbeiten. KDE 3 ist eine gute Wahl um Fehler zu beseitigen, die Hauptentwicklung (mit den neuen Features) findet jedoch in KDE 4 statt. Dieses Dokument bezieht sich hauptsächlich auf die Unterstützung von KDE 4.

=== C++ ===
KDE ist hauptsächlich in C++ geschrieben. Wenn Sie nicht mit C++ vertraut sind, sollten Sie sich etwas einarbeiten. Es gibt eine Anzahl an guten Büchern für C++ - eine ausgezeichnete Quelle ist [http://mindview.net/Books/TICPP/ThinkingInCPP2e.html Bruce Eckel's "Thinking in C++"], welches als freier Download und in gedruckter Form erhältlich ist. Es ist nicht nötig alles zu verstehen bevor man an KDE beginnt, aber Sie müssen die grundlegende Syntax und den Arbeitsablauf verstehen.

=== Qt ===
Um in der KDE-Programmierung Kompetenz zu erlangen, sollten Sie das Qt-Toolkit beherrschen. Wenn Sie nicht mit Qt vertraut sind, sollten Sie die in Qt ([http://doc.trolltech.com/latest/examples.html Version 4], [http://doc.trolltech.com/3.3/tutorial.html Version 3]) enthaltenen Übungen durchgehen.

Wenn Sie mehr zu Multimedia und Videos neigen, möchten Sie vielleicht zum Start zwei erstaunliche Minuten mit dem Video [http://www.trolltech.com/trolltech/products/qt/learnmore/video/demos/browser Building a Simple Help Documentation Browser with Qt4 Designer] verbringen. Wenn es Ihre Aufmerksamkeit errang, können Sie auch die Video-Einführung [http://www.trolltechvideo.com/video/day1/room_a/a_1_1/video.html Hello Qt] von Mark Summerfield ansehen, welches ein Teil der [http://www.trolltech.com/company/newsroom/events/allevents/devdays2006/videolinks Trolltech Developer Days 2006 presentations] ist.

Wenn Sie eine genauere Qt-Einführung oder nur eine alternative Sichtweise benötigen, dann können Sie einen Blick auf [http://qt4.digitalfanatics.org/tiqt/ The Independent Qt Tutorial] werfen (zurzeit offline wegen eines Buchvertrages).

Mehr Anregungen wie man mit Qt 4 vertraut wird
[http://doc.trolltech.com/latest/how-to-learn-qt.html gibt es auch hier]. Eine Kopie des Dokumentes wird auch in Qt 4 bereitgestellt.

=== KDE ===
Eine Auswahl an Informationen über die KDE-Techniken ist erhältlich in dem [[Development/Tutorials|Einleitungsabschnitt]]. Beachten Sie dass einige der dortigen Einleitungen immer noch KDE 3 betreffen, welche jedoch zumindest teilweise übertragbar sind.

Sie werden auch nützliche Informationen in dem [[Development/FAQs|FAQs]]-Abschnitt finden. Diese Informationen könnten für KDE 4 überholt sein, aber vieles ist allgemein anwendbar, sogar außerhalb von KDE.

Sie können auch die [[Development/Further Information|KDE-Programmierungs-Bücher]] lesen.

Als letztes, aber nicht minder wichtig: KDE kommt mit einer umfangreichen Klassen-Dokumentation (API, Application Programmer Interface). Diese ist im Abschnitt [[Development/Tutorials/API Documentation|KDE API Referenz Manuals]] erhältlich, welche auch eine Menge an nützlichen Verweisen über das Schreiben oder Aktualisieren einer Klassen-Dokumentation beinhaltet. Sie können diese auch entweder selber auf Ihrer eigenen Maschine herstellen oder auf eine aktuellere Online-Version des [http://www.englishbreakfastnetwork.org/apidocs/apidox-kde-4.0/kdelibs-apidocs/ English Breakfast Network] zugreifen.

Eine detailliertere Beschreibung der oben genannten Schritte ist erhältlich in unserem
[http://quality.kde.org/develop/howto/howtohack.php Programmierungs-Leitfaden].

== Beteiligung an der Fehlerjagd und der Anwendungs-Qualität ==

Es existieren eine Reihe Anwendungen innerhalb KDE und nicht alle haben einen zugeordneten Maintainer, der sich um Fehler und die allgemeinen Aufgaben, die das Umwandeln des funktionierenden Codes in eine ausgefeilte Anwendung kümmert.

Wenn Sie an einer Mitarbeit an KDE interessiert sind, aber nicht wissen wo Sie anfangen sollen, könnte Ihnen eine Mitgliedschaft in dem KDE-Qualitäts-Team gefallen - für weitere Informationen, sehen Sie dazu die [http://quality.kde.org Qualitäts-Team-Webseite] an. Sie brauchen keine Programmierfähigkeiten um sich zu beteiligen.

Natürlich können Sie sich an der Fehlerjagd beteiligen ohne ein Teil des KDE-Qualitäts-Teams zu sein - erstellen Sie dazu einfach einen Account im [http://bugs.kde.org Fehlerverfolger], und starten Sie das Aussortieren / Suchen durch die Fehlermeldungen.
Nochmals, Sie brauchen keine Programmierfähigkeiten - es hilft den Programmierern enorm eine Vorgehensweise zu haben um einen Fehler reproduzieren zu können.

Die [[Contribute/Bugsquad|Fehlertruppe]] versucht, den Fehlermeldungen zu folgen, und stellt sicher dass gültige Fehler von den Programmierern wahrgenommen werden. Sie brauchen kein Programmierwissen um in der Fehlertruppe zu sein; in der Tat, es ist ein großartiger Weg um der KDE-Gemeinschaft etwas zurückzugeben, wenn Sie nicht programmieren können.

== Historische Quellen ==

; [http://www.kerneltraffic.org/kde/ Kernel Cousin KDE]
: Eine Zusammenfassung der Entwicklungs-Mailinglisten. Der Kernel Cousin KDE erschien mit 76 Ausgaben vom 10 März 2001 bis zum 16 April 2004. Der KDE-Commit-Digest (oben beschrieben) ist sein logischer Nachfolger.

Development/Architecture (de)

2008-01-18T14:15:35Z

DrSlowDecay: Page created

{{Template:I18n/Language Navigation Bar|Development/Architecture}}
Die folgenden Seiten beinhalten detailierte Dokumentationen über das Design und die Architektur von KDE. Sie ersetzen nicht die anderen Dokumentationen wie [http://api.kde.org API Dokumentation (englisch)], [[../Tutorials|tutorials/howtos]] und [[../Guidelines|standards]], siehe auch das [[Development (de)|Entwickler Portal]] für weitere Informationen.

Für ein besseren Verständnis könnte es helfen sich mit Trolltech's™ excellenter [http://doc.trolltech.com/3.3/index.html Qt 3.3] oder [http://doc.trolltech.com/4.3/index.html Qt 4.3] Dokumentation und deren [http://www.trolltech.com/developer/ Entwickler Seiten] zu beschäftigen.

Für mehr Informationen über eine KDE Installtion sehen Sie bitte auch die entsprechenden Kapitel in [[KDE System Administration|System Administration]].

== Design Dokumente ==
; [[Development/Architecture/KDE4|KDE 4 Architecture Overview]]
: Ein Überblick über die KDE 4 Architektur einschließlich Diskussionen über allgemeine Techniken, Bibliotheksklassen und allgemeine Entwicklerfragen. Gilt für ''KDE 4.0''.

; [[Development/Architecture/KDE3|KDE 3 Architecture Overview]] [http://developer.kde.org/documentation/library/kdeqt/kde3arch/ (Original)]
: Ein Überblick über die KDE 3 Architektur einschließlich Diskussionen über allgemeine Techniken, Bibliotheksklassen und allgemeine Entwicklerfragen. Gilt für ''KDE 3.0''.

; [http://developer.kde.org/documentation/library/kdeqt/kde2arch/ KDE 2 Architecture Overview]
: Ein Überblick über die KDE 2 Architektur einschließlich Diskussionen über allgemeine Techniken, Bibliotheksklassen und allgemeine Entwicklerfragen. Gilt für ''KDE 2.2''.

; [[Development/Architecture/DCOP|DCOP]]
: Design Dokumente von 1999-2000.

[[Category:Architecture]]

Getting Started/Sources/Subversion (de)

2008-01-18T13:59:54Z

DrSlowDecay: Page copy from english version

{{Template:I18n/Language Navigation Bar|Getting Started/Sources/Using Subversion with KDE}}

{{TutorialBrowser (de)|

series=Anfang|

name=Subversion mit KDE benutzen|
}}

== Zusammenfassung ==

This is a quick KDE-specific introduction for using subversion to access files and software in KDE's repositories. For comprehensive coverage of Subversion we recommend reading the book
"[http://svnbook.red-bean.com/ Version Control with Subversion]".

== Am Anfang ==

In order to use the KDE Subversion repository, you will need two things:

# A Subversion client program
# An account in our repository

Note: For anonymous read-only access use protocol "svn", no "yourname@" and server "anonsvn.kde.org" instead below.

'''Installing Subversion:''' instructions on installing the client are not
presented here. Refer to your system installation instructions to find out how
you can install Subversion. You will need version 1.1 at least. If you are
compiling from sources and want to access the KDE repository by https
(and not by svn+ssh), you will need SSL and ZLIB support,
so you will need the <tt>--with-ssl --with-zlib</tt> options.

Alternatively, you can install one of the many graphical clients out there.
This tutorial is intended for people using the <tt>svn</tt> program only, referring
to tasks accomplished with the usual <tt>cvs</tt> program.

'''Getting an account:''' if you had a CVS
account before, it has been migrated to the new Subversion client. If
you didn't, refer to the [[Contribute/Get_a_SVN_Account|corresponding tutorial]] how to get one.

{{Note (de)|If you have lost your CVS password, there are simple ways to retrieve
it. Use [http://ktown.kde.org/~coolo/cvspwd.c cvspwd.c] or [http://kdab.net/~dfaure/cvs-unscramble cvs-unscramble] (Perl).}}

== Die Struktur des KDE Repository ==

svn.kde.org/home/kde

That's the address of the KDE Subversion repository. The repository is served by
HTTPS or SVN+SSH protocol, which means your password is secure against third-party
eavesdropping.

The SSL certificate md5 fingerprint for the repositories:
F6BF EDE2 D016 D1B2 4F18 742E 2C8F B7EF

The SSL certificate sha1 fingerprint for the repositories:
e1:e6:41:96:3c:eb:ae:78:e2:73:0d:a2:32:2f:6b:21:13:bf:3d:0f

For people using svn+ssh, here's the fingerprint of the server's RSA key:
86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb

The repository is organised in main directories:

# /branches
# /tags
# /trunk

You can explore the repository structure at [http://websvn.kde.org/ http://websvn.kde.org/]

=== Das Unterverzeichnis /trunk ===

The <tt>/trunk</tt>
top-level subdirectory is where the main development for KDE occurs.
What you will find here is what will become the next KDE release, and
its associated programs. Here you will also find the <tt>www</tt> module,
which contains webpages for KDE's site and related ones.

<tt>/trunk</tt> is further subdivided into these sub-directories:

*<tt>KDE/</tt> KDE itself, what will become the next public release. It contains the following modules:
**'''kdelibs''' - KDE basic libraries, used by all KDE programs
**'''kdebase''' - KDE base programs, like the KDE Control Center, Kicker (the panel) and Konqueror (the web browser)
**'''kdeaccessibility''' - Accessibility files
**'''kdeadmin''' - KDE Administration applications
**'''kdeartwork''' - Images, themes, sounds and other art files
**'''kdebindings''' - Bindings for languages other than C++
**'''kdeedu''' - KDE Educational applications
**'''kdegames''' - KDE Games
**'''kdegraphics''' - KDE Graphical applications
**'''kdemultimedia''' - KDE Multimedia applications
**'''kdenetwork''' - KDE Networking applications
**'''kdepim''' - KDE Personal Information Management applications
**'''kdepimlibs''' - Libraries used by KDE-PIM applications.
**'''kdesdk''' - KDE Software Development Kit applications
**'''kdetoys''' - KDE toy applications
**'''kdeutils''' - KDE General utilities
**'''kdevelop''' - The KDevelop program
**'''kdevplatform''' - The development platform which KDevelop is based on
**'''kdewebdev''' - KDE Web development applications
*<tt>kde-common</tt>
:Common admin/ directory
*<tt>bugs/</tt>
:[http://bugs.kde.org/ Bugzilla] files
*<tt>developer.kde.org/</tt>
:The content of developer.kde.org
*<tt>extragear/</tt>
:KDE programs outside the main KDE releases.
*<tt>kdereview/</tt>
:Temporary home for KDE applications that are believed to have reached release-quality. From here, once all major issues are resolved, applications are moved either to <tt>/trunk/KDE/</tt> or to <tt>/trunk/extragear/</tt>
*<tt>kdesupport/</tt>
:Supporting applications and libraries for KDE
*<tt>koffice/</tt> The KDE Office suite, containing the programs:
**'''karbon'''
**'''kchart'''
**'''kexi'''
**'''kformula'''
**'''kivio'''
**'''koshell'''
**'''kplato'''
**'''kpresenter'''
**'''krita'''
**'''kspread'''
**'''kugar'''
**'''kword'''
*<tt>konstruct/</tt>
:Konstruct, the KDE build program
*<tt>l10n-kde3/</tt>
:Translations for the "unstable" modules of KDE 3 (extragear, playground)
*<tt>l10n-kde4/</tt>
:Translations for KDE 4
*<tt>playground/</tt>
:The KDE playground: applications being developed, but not having yet reached release-quality.
*<tt>qt-copy/</tt>
:The convenience copy of [http://www.trolltech.com/ Trolltech's] Qt library, which KDE is based upon.
*<tt>tests/</tt>
:khtml, KOffice and ksvg testcases
*<tt>valgrind/</tt>
:The Valgrind application, which is hosted on the KDE repository, but that is not part of KDE itself. Note that newer versions of Valgrind are developed on their own repository. The KDE Valgrind modules only holds up to Valgrind 2.4.
*<tt>www/</tt>
:Webpages for the KDE site (and related sites). Write access to this directory is restricted.

=== Das Unterverzeichnis <tt>/tags</tt> ===

This
directory contains the official releases of the programs maintained and
developed in the KDE repository. Each individual application has a
subdirectory here. Inside it, you will find the release numbers.

For instance, the KDE 3.4.0 code can be found under <tt>/tags/KDE/3.4.0/</tt>.

=== Das Unterverzeichnis <tt>/branches</tt> ===

This directory contains the branch versions of the applications after a major release.

Most
KDE applications adhere to the philosphy that new features (as well as
new user-visible strings) are added only to the next release cycle —
the one that lives in <tt>/trunk/</tt>. However, bugfixes are applied to all
applications, even after release.

In
order to do that, a branch is created at the moment of the release,
indicating the state of the files at that time. Bugfixes are then
checked in to those files. Those branches are the ones in <tt>/branches/</tt>.

For instance, the KDE 3.4.x branch can be found under <tt>/branches/KDE/3.4/</tt>

The subdirectories you will find inside <tt>/branches</tt> are the
application subdirs, like <tt>akregator/</tt>, <tt>amarok/</tt>,
<tt>arts/</tt>, <tt>k3b/</tt>, etc. You will also find a <tt>KDE/</tt>
subdir, containing the official KDE releases since time immemorial.

One special subdir is found in <tt>/branches</tt>: <tt>work/</tt>. This
subdir contains the so-called "work branches", that is, branches containing
features being worked on, sometimes highly experimental. Multi-application
work branches always are checked in to <tt>/branches/work/</tt>, but
single-application branches may be found in each application's subdir. That
is a decision left to the developers.

== Auschecken und Aktualisieren ==

=== Auschecken ===
In order to check out something with Subversion, you use the <tt>checkout</tt> subcommand.

'''WARNING:''' If you checkout trunk/KDE/ or branches/KDE/foo/ you will download complete kde-i18n!

Suppose you wanted to check out only KDevelop from the KDE repository. You would do:

CVS command:
cvs -d :pserver:yourname@cvs.kde.org:/home/kde login
cvs -d :pserver:yourname@cvs.kde.org:/home/kde checkout kdevelop

Subversion command:

CVS users currently using ssh access, should use protocol svn+ssh,
CVS users currently using password access, should use protocol https
in the following.

svn checkout <protocol>://<username>@svn.kde.org/home/kde/trunk/KDE/kdevelop

=== Aktualisieren ===

In order to update, you use the <tt>update</tt> subcommand.

This is no different from CVS: you change into your checked out copy (for those new to this whole process, the checked out copy should be in your Home folder) and issue a <tt>svn update</tt> (or, shorter, <tt>svn up</tt>) command.

== Den Status einer Datei ermitteln ==

To know which local files you had modified, in CVS most people did
cvs up
and looked at the files with '''M''', this does not work with svn so you have to do
svn status
to know the status of the files.

== Ins Repository hochladen ==

Just like in CVS, committing to the Subversion repository is accomplished
with the <tt>commit</tt> or <tt>checkin</tt> (<tt>ci</tt> for short) subcommands.

CVS command:
cvs commit
# or
cvs ci
# or
cvs ci filename.cpp

Subversion command:
svn commit
# or
svn ci
# or
svn ci filename.cpp

This way, <tt>svn</tt> will launch the editor specified in <tt>$SVN_EDITOR</tt> for you
to compose the commit message. If you prefer, you can give <tt>svn</tt> the -m
oprtion with your full message:

svn ci -m "Updating protocol to conform to HTTP/1.1"

== Dateien ignorieren ==

Subversion stores ignored files per directory. To edit the ignored
files of the directory you are currently in, do
svn propedit svn:ignore .
that will launch your editor, write there the names of the files you want to
ignore, one file per line. Once you are done, do a commit so the ignored list
file gets updated on the server.

A lot of files were ignored in CVS with help from global ignore list which
is not supported yet by SVN. You can wait for svn 1.3 or you need to add the
ignore list to the [miscellany] group in your {{path|~/.subversion/config}} (all in
one line):

global-ignores = *.o *.lo *.la .*.rej *.rej .*~ *~ .#* #*# .DS_Store *.moc
*.moc.cc *.moc.cpp config.log config.status config.cache *.gmo .deps .libs
SunWS_cache *.lo *.la *.rpo *.la.closure *_la_closure.cpp *_la_closure.cc
*_la_closure.cxx *.all_cc.cc *.all_cpp.cpp *.all_C.C *.all_cxx.cxx
*_meta_unload.cc *_meta_unload.h *_meta_unload.cpp *_meta_unload.C
*_meta_unload.cxx index.cache.bz2 .memdump Makefile.rules.in Makefile.calls.in
Makefile.rules Makefile.calls autom4te.cache *.kidl

== Working with multiple revisions and branches ==

Unlike CVS, Subversion doesn't generate a revision number for each file
modified. Instead, the full repository is versioned, as a whole. This way, a
given revision number represents the state the repository was on a given date.
In other words, a revision number is like a timestamp (in fact, the Subversion
server uses this fact to search for dates in the repository faster).

So, for instance, when you check out the KDE repository, Subversion will
tell you the following:

Updated to revision 403821.

This means that the latest revision available at the time of the operation
was 403821. If you make a modification and commit, Subversion will update the
server-side revision and will inform you of it. Like CVS, only the committed
files will be updated: you will need run <tt>cvs up</tt> to update the rest of the
files.

If you want to retrieve a specific revision of a file, you can use the <tt>-r</tt>
switch. Besides the revision number itself, -r accepts a number of other
possibilities:

* The revision number: for example, use -r 403819 to retrieve that version
* '''BASE''': the revision you updated to
* '''COMMITTED''': the revision a file was last modified, before BASE
* '''PREV''': the revision of the previous commit to the file before COMMITTED
* '''HEAD''': the most recent revision available in the server
* '''{ date }''': between curly brackets, you can specify a date for searching the closest revisions

The following illustrates the evolution of the keywords:

# You run <tt>svn up</tt> to update to the latest available revision. Suppose Subversion tells you it updated to revision 403821. This means that HEAD and BASE are 403821.
# You modify file README and commit it. Suppose Subversion tells you it committed revision 403822. This means HEAD, BASE and COMMITTED are 403822.
# You modify the file again and commit it. Now PREV is 403822, but HEAD, BASE and COMMITTED are updated to a new value (suppose it's 403823).
# Now someone else modifies the repository, and you update your working copy. If Subversion tells you it updated to 403824, this means now HEAD and BASE are moved to 403824 (but PREV and COMMITTED stay the same)
# If someone modifies the README file now, HEAD is moved. The other keywords stay the same for you, until you update. At this time, we will have HEAD = 403825 (the latest available revision), BASE = 403824 (the revision you last updated to), COMMITTED = 403823 (the revision of the latest change to the file when you last updated) and PREV = 403822 (the revision of the change before COMMITTED)

Those keywords are useful to retrieve logs and diffs for commits to the
repository.

If you want to see the difference between your working copy and BASE, you
can run:

svn diff

This is a very fast operation, since Subversion keeps a local copy of BASE.
It doesn't need a network connection to accomplish this operation.

If you want to see the difference between your local copy and the latest
available on the server, you will run:

svn diff -r HEAD

If you want to see what has changed in the repository since you've last updated, you can use:
svn diff -r BASE:HEAD

If you want to see the last change to a file before BASE, you can use:
svn diff -r PREV:BASE
# or
svn diff -r PREV:COMMITTED

That is also valid for the <tt>svn log</tt> command.

== Unterverzeichnisse von anderen Orten verlinken ==

It can happen you would like to include a copy of a subdirectory from another place, but just for convenience, not for developing the code in there. Of course it should be updated automatically whenever the original changes. Subversion can help you. You need to edit the property <tt>svn:external</tt> of the directory the subdirectory should be added to. So for the current directory you use
svn propedit svn:externals .
and then enter lines of the form
libkhalkhi svn://anonsvn.kde.org/home/kde/trunk/playground/pim/khalkhi
Updating will now fetch <tt>/trunk/playground/pim/khalkhi</tt> into the subdirectoy <tt>libkhalkhi</tt>.

{{warning (de)|Beware that you cannot commit changes you did to the local copy of the external subdirectory, it is just a readonly copy.}}

You use <tt>svn://anonsvn.kde.org</tt> and not another protocol, because <tt>anonsvn.kde.org</tt> is accessible to everyone. Using <tt>https:</tt> or <tt>svn+ssh:</tt> would only work for users of that protocol. There are still some small disadvantage with <tt>anonsvn.kde.org</tt>: It is not always in synchronization with <tt>svn.kde.org</tt>, so updates in the original branch may take a while to appear on <tt>anonsvn.kde.org</tt>. And some strict firewalls are blocking the <tt>svn:</tt> protocol.

A special case in KDE 3 is the subdirectory <tt>admin</tt>, containing the KDE 3 build utilities. It is linked in to the top directory in all modules, and maintained in <tt>/branches/KDE/3.5/kde-common</tt>. For <tt>admin</tt> the KDE subversion server is configured to allow readonly access for everyone, so if you see
admin https://svn.kde.org/home/kde/branches/KDE/3.5/kde-common/admin
there is no need to change this.

== Mehr Informationen im KDE Wiki ==

See [http://wiki.kde.org/tiki-index.php?page=KDE%20Subversion%20HOWTO the KDE wiki] for more
information about subversion in KDE

Getting Started/Build/KDE4 (de)

2008-01-18T13:45:10Z

DrSlowDecay: Changed to german templates

{{Template:I18n/Language Navigation Bar|Getting_Started/Build/KDE4}}

{{TutorialBrowser (de)|

series=Vorbereitungen|

name=KDE4 aus dem Quellcode bauen|

pre=[[../../Sources/Anonymous_SVN|Anonymous SVN Quickstart Guide]]|

next=[[../../Set_up_KDE_4_for_development|Set up KDE 4 for development]]|

reading=[http://kdesvn-build.kde.org/ kdesvn-build: The KDE From Subversion Build Tool] [[../../Increased_Productivity_in_KDE4_with_Scripts|Increased Productivity in KDE4 with Scripts]] [[Development/Tutorials/CMake |Introduction to CMake]] [[../KDE4/FreeBSD|FreeBSD notes]] [[../KDE4/Mac OS X|Instructions for Mac OS X]]|
}}

== Übersicht ==

Diese Anleitung zeigt einen Weg, KDE auf Linux- und BSD-Systemen
zu komplieren und auszuführen. Als Grundlage verwenden wir die Shell.
Wenn Sie sich für die Installation auf anderen Systeme wie etwa Solaris, MacOS oder Microsoft Windows interessieren, besuchen Sie bitte [[../|Build]] und folgen Sie den Links am Ende der Seite.

{{warning (de)|Stellen Sie sich auf verstärkt auftretende Buildprobleme '''an Montagen''' ein, da die Entwickler an diesem Wochentag kritische Änderungen vornehmen. Das [http://developer.kde.org/~dirk/dashboard/ Dashboard] zeigt unerwartete Probleme beim Kompilieren an.
}}

== Benötigte Software ==

Folgendes muss installiert sein, um dieses Tutorial erfolgreich durchführen zu können:
* gcc und g++ vom gcc Projekt, vorzugsweise Version 4.1 oder höher
* svn, der subversion revision control client
* pkg-config
* devel-(Entwicklungs-)Bibliotheken und -header für X11, OpenGL (mesa-common-dev und libglu1-mesa-dev), libjpeg, libpng, libungif, [http://clucene.sourceforge.net/index.php/Downloads libclucene], [http://download.librdf.org/source/ librdf], libxml2 und libxslt
* Das <tt>makeobj</tt> Skript, welches Teil von kdesdk ist. Sie können es als Teil von kdesdk (kdesdk-scripts in Debian) installieren oder von hier einzeln herunterladen: [http://websvn.kde.org/*checkout*/trunk/KDE/kdesdk/scripts/makeobj WebSVN]
* das [http://freedesktop.org/wiki/Software/shared-mime-info shared-mime-info Paket], welches der freedesktop-MIME-Standard ist, den KDE nun nutzt
* [http://boost.org/ boost], welches von kdebase gebraucht wird. Nach dem Kompilieren und/oder Installieren von boost fügen Sie das boost-Verzeichnis (das, welches das include-Unterverzeichnis enthält) zu CMAKE_INCLUDE_PATH hinzu, oder kreieren Sie eine Umgebungsvariable namens BOOST_ROOT, die zum boost-Verzeichnis verweist, um cmake den Ort von boost mitzuteilen (FindBoost).

Weiterhin ist es zu empfehlen, folgende Software bereits installiert zu haben:
* bash

=== Kubuntu ===

In Kubuntu 7.04 (Feisty) können alle zum Bau der Pakete benötigte Software mit folgendem Befehl installiert werden:
<code bash>
sudo aptitude install build-essential cdbs debhelper cmake libungif4-dev \
libxml2-dev libxslt1-dev libbz2-dev libclucene-dev librdf-dev \
shared-mime-info libgl1-mesa-dev libglu1-mesa-dev mesa-common-dev \
libxext-dev libjpeg-dev libpng-dev libsm-dev libxinerama-dev \
libxrender-dev libfontconfig-dev libboost-dev libxcursor-dev doxygen
</code>

Die manuelle Installation von Qt 4.3, CMake 2.4.6 und DBus kann durch die Installation der folgenden Pakete und ihrer Abhängigkeiten vermieden werden:
<code bash>
sudo aptitude install libqt4-dev-kdecopy libdbus-1-dev cmake
</code>

{{warning (de)|Alle KDE-Releases nach Alpha1 funktionieren nur mit Qt4.3. Kubuntu hat aber nur Pakete für Qt 4.3-Beta. Um neuere Versionen zu kompilieren, ist das offizielle Release nötig.
}}

Für eine voll funktionstüchtige [[apidox]]-Umgebung wird ebenfalls zusätzliche Software benötigt:
<code bash>
sudo aptitude install graphviz
</code>

=== openSUSE ===
{{note (de)|
Der openSUSE build service stellt ebenfalls tagesaktuelle KDE-4-Pakete bereit, die das gesamte auf dieser Seite beschriebene Vorgehen überflüssig machen. Weitere Informationen findet man direkt im openSUSE wiki unter [http://de.opensuse.org/KDE4 KDE4].
}}

In OpenSuse können Pakete mit Hilfe von [http://de.opensuse.org/Zypper Zypper] installiert werden:
<code bash>
sudo zypper install <package-name>
</code>

In älteren SUSE-Versionen geht dies nur mit Yast:
<code bash>
yast2 -i <packagename>
</code>

Die meisten zum Bau von KDE 4 nötigen Pakete sind:
<code bash>
xorg-x11-devel, libxml2-devel, kdesdk3, clucene-core-devel, libjpeg-devel, liblrdf-devel, libpng-devel, libxslt-devel, Mesa-devel, giflib-devel, subversion, gcc, gcc-c++
</code>

Bereits vorkompilierte CMake-Pakete für openSUSE sind direkt verfügbar im [http://software.opensuse.org/download/devel:/tools:/building/ openSUSE build service].

=== Gentoo ===

Sie können die stabilen ebuilds verwenden. Vergessen Sie nur nicht, ihr Portage zu synchronisieren, bevor Sie fortfahren.

Von folgenden Paketen müssen instabile Versionen verwendet werden. Um das zu erreichen, nehmen Sie die Paketnamen in die Datei <code>package.keywords</code> auf.

<code bash>
# echo 'x11-libs/qt' >> /etc/portage/package.keywords
# echo 'dev-util/cmake' >> /etc/portage/package.keywords
# echo 'dev-cpp/clucene' >> /etc/portage/package.keywords
# echo '>dev-cpp/clucene-0.9.16a' >> /etc/portage/package.mask
</code>

Dies sind die zu installierenden Pakete. Einige könnten bereits installiert sein. Diese können übersprungen werden, indem das "update"-flag in emerge gesetzt wird.

<code bash>
$ emerge -avu ebuild/name
</code>

sys-devel/gcc
dev-util/subversion
dev-util/pkgconfig
x11-base/xorg-x11
media-libs/glut
media-libs/mesa
media-libs/jpeg
media-libs/libpng
media-libs/giflib
dev-cpp/clucene
dev-util/cppunit
media-libs/liblrdf
dev-libs/libxml2
dev-libs/libxslt
x11-misc/shared-mime-info
dev-libs/boost
x11-libs/qt
dev-util/cmake
sys-apps/dbus
redland

Beginnen Sie nun, [[Getting_Started/Build/KDE4#Strigi|Strigi]] zu kompilieren.

Viel Erfolg!

== Ein Benutzer für die KDE-4-Entwicklung ==

{{Note (de)|
Einige Menschen ziehen es vor, für KDE 4 einen separaten Nutzer-Account einzurichten, um nicht aus Versehen durch noch bestehende Bugs oder ähnliches Daten zu verlieren. Die Anleitung hier basiert auf der Herangehensweise.

Es ist jedoch deutlich effizienter alles mit einem einzigen Nutzer-Account zu machen. Unter [[Getting_Started/Increased_Productivity_in_KDE4_with_Scripts|Increased Productivity in KDE4 with Scripts]] findet man mehr Details dazu.

In diesem Fall ist die folgende Anleitung noch immer gültig, jedoch sollten die nötigen Umgebungsvariablen nicht in die <tt>.bashrc</tt>, sondern in eine separate Datei geschrieben werden, die dann bei Bedarf eingelesen wird.
}}

=== Option 1: Kommandozeile ===
<code bash>
useradd -m kde-devel
passwd kde-devel
</code>

=== Option 2: Über KControl ===

Anstatt der oben genannten Befehle kann man auch mit Hilfe des Benutzer-Moduls im KDE-Kontrollzentrum (kcontrol) einen weiteren Benutzer einrichten.

=== Einrichten der Entwicklungsumgebung ===

Kopieren Sie die Datei {{path|~/.bashrc}} von Ihrem normalen Benutzer-Account zu Ihrem neuen kde-devel-Account. Danach fügen Sie den Inhalt der Seite [[Getting Started/Increased Productivity in KDE4 with Scripts/.bashrc|example .bashrc]] in die Datei {{path|~kde-devel/.bashrc}} ein. Stellen Sie sicher, dass die Zeile <tt>alias make=makeobj</tt> auskommentiert ist falls auf Ihrem System das Programm <tt>[[Getting Started/Build/KDE4#Required Software|makeobj]]</tt> nicht verfügbar ist.
Die neue {{path|~/.bashrc}} wird mit folgendem Befehl eingelesen:
<code bash>
source ~/.bashrc
</code>

Nun haben Sie Zugriff auf Befehle wie <tt>cmakekde</tt>, die in dieser Anleitung genutzt werden. Auch wird so sichergestellt, dass alle wichtigen Umgebungsvariablen (z. B. für die Pfadangaben von Qt, KDE und CMake) richtig gesetzt sind.

Für weitere Informationen lesen Sie bitte [[Getting Started/Increased Productivity in KDE4 with Scripts]].

=== Zum neuen Benutzer wechseln ===

Sie können sich nun als Benutzer kde-devel anmelden (der Bindestrich ist wichtig!):
<code bash>
su - kde-devel
</code>

Der Rest dieser Anleitung geht davon aus, dass Sie alle Befehle als <tt>kde-devel</tt> ausführen.

== Die Shell des Entwicklungsbenutzers ==
Auf manchen Systemen nutzen neue Benutzer standardmäßig {{path|/bin/sh}}. Wenn dies auf Ihrem System nicht der Fall ist, können Sie diesen Abschnitt überspringen. {{path|/bin/sh}} zu nutzen kann sich als sehr unangenehm erweisen. Daher sollten Sie erwägen, zu {{path|/bin/bash}} oder einer anderen Shell zu wechseln.

=== Option 1: Als kde-devel-Benutzer ===
Wenn Sie keine root-Privilegien haben und Ihr System das Wechseln der eigenen Shell mittels <tt>chsh</tt> unterstützt, können Sie versuchen, Ihre Shell zu {{path|/bin/bash}} zu wechseln, indem Sie Folgendes eingeben:
<code bash>
chsh -s /bin/bash kde-devel
</code>

=== Option 2: Als root-Benutzer ===
Wenn Ihr System die Anwendung <tt>usermod</tt> beinhaltet, können Sie den folgenden Befehl als root-Benutzer eingeben: <tt>usermod -s /bin/bash kde-devel</tt>.

Eine weitere Möglichkeit ist die Nutzung der Anwendung <tt>vipw</tt> als root-Benutzer, um auf sichere Art {{path|/etc/passwd}} zu editieren. Machen Sie 'kde-devel' in dieser Datei ausfindig und ändern Sie '{{path|/bin/sh}}' am Zeilenende in '{{path|/bin/bash}}'. Speichern Sie die Änderungen und beenden Sie die Anwendung.

Die neue Shell wird automatisch gestartet wenn Sie sich wieder als kde-devel-Benutzer einloggen.

== D-Bus ==
QtDBus und KDE arbeiten mit den D-Bus-Versionen 0.6.2, 0.92 und höher zusammen. Die Versionen 0.60 und 0.61 funktionieren eventuell auch, sind aber ungetestet. Die Versionen 0.90 und 0.91 funktionieren definitiv nicht.

Wir empfehlen, dass Sie eine aktuelle, stabile Version, also größer Version 1.0, benutzen, wenigstens aber Version 0.94.

Wenn Sie eine aktuelle D-Bus-Version auf ihrem System bereits installiert haben oder Ihre D-Bus-Version nicht aktualisieren wollen, können Sie die nächste Sektion überspringen.

Bevor Sie die nächsten Schritte durchgehen sollten Sie sicherstellen, dass die X11-header und -Bibliotheken installiert sind. Das Konfigurationsskript sollte in Zeile 5 Folgendes ausgeben:
Building X11 code: yes

=== Das Kochrezept ===

{{tip|Stellen Sie sicher, dass Ihre Umgebung [[Getting_Started/Build/KDE4 (de)#Einrichten der Entwicklungsumgebung|wie beschrieben]] eingerichtet wurde. Das ist wichtig für das Funktionieren der <tt>cs</tt>- und <tt>cb</tt>-Befehle.}}

cs # [[Getting_Started/Increased_Productivity_in_KDE4_with_Scripts/.bashrc|'cs' ist eine Bash-Funktion, klicken Sie hier, um mehr darüber zu lernen]]
wget http://dbus.freedesktop.org/releases/dbus/dbus-1.0.2.tar.gz
tar -xvzf dbus-1.0.2.tar.gz
cd dbus-1.0.2/
./configure --prefix=$DBUSDIR --localstatedir=$KDEDIR/var
make
make install
dbus-uuidgen --ensure

=== Was hier passiert ===
Wir wechseln in Zeile 1 in das Quellen-Verzeichnis, laden in Zeile 2 den Quellcode von freedesktop.org herunter und entpacken diesen in Zeile 3.
In Zeile 4 wechseln wir in das neu erstellte Verzeichnis, und bereiten in Zeile 5 das Kompilieren der Quelldateien vor. Zeile 6 setzt den Kompilier-Vorgang in Gang, Zeile 7 installiert D-Bus, und in Zeile 8 benutzen wir das <tt>dbus-uuidgen</tt>-Werkzeug, um eine Maschinen-Identifikation zu installieren. Das erlaubt dem bus, automatisch mit der Desktop-Sitzung zu starten.

Achten Sie darauf, dass Sie Schreibrechte auf {{path|/var}} haben, da Sie sie für die letzten beiden Schritte benötigen. Falls Ihr System kein sudo-Kommando unterstützt, können Sie auch <tt>su</tt> benutzen, z. B. <tt>su -c "make install"</tt>.

=== Fehlerbehebung ===

Falls Sie die Fehlermeldung '''makeobj: command not found''' bekommen fehlt Ihnen <tt>[[Getting_Started/Build/KDE4#Required_Software|makeobj]]</tt>.

== CMake ==
Überspringen Sie diesen Abschnitt, wenn Sie [http://cmake.org/ CMake] >=2.4.5 installiert haben.
Es sollte Ihnen möglich sein, die Binärpakete zu installieren, die hier verfügbar sind: [http://www.cmake.org/HTML/Download.html CMake site]. Dort sind ebenfalls distributionsspezifische Pakete zu finden.

=== Das Kochrezept ===


cs # [[Getting_Started/Increased_Productivity_in_KDE4_with_Scripts/.bashrc|'cs' ist eine Bash-Funktion, klicken Sie hier, um mehr zu erfahren]]
wget http://www.cmake.org/files/v2.4/cmake-2.4.6.tar.gz
tar zxf cmake-2.4.6.tar.gz
mkdir cmake-build
cd cmake-build
../cmake-2.4.6/bootstrap
make
sudo make install

=== Was hier passiert ===
Zuerst wechseln wir in das Quellverzeichnis des <tt>kde-devel</tt>-Benutzers (Zeile 1), laden den CMake-Quellcode herunter (Zeile 2) und entpacken ihn (Zeile 3). Dann erstellen wir ein Verzeichnis, in dem wir CMake kompilieren (Zeile 4) und wechseln in dieses (Zeile 5). Hier führen wir das CMake-bootstrap-Skript aus (Zeile 6), dann den make-Befehl (Zeile 7) und schließlich die Installation als root-Benuzter (Zeile 8).

Wenn Ihr System den <tt>sudo</tt>-Befehl nicht beinhaltet, können Sie stattdessen Folgendes eingeben: <tt>su -c "make install"</tt>.

== Qt ==
Als nächstes wird Qt 4 benötigt; es befindet sich im KDE-Quell-Repository. KDE kompiliert garantiert gegen jedes Qt der Version 4.3. Qt 4.2 und früher sind nicht unterstützt und funktionieren nicht. Da Qt 4.3 erst kürzlich veröffentlicht worden ist, finden sich wahrscheinlich noch keine Pakete für Ihre Distribution (bekannte Ausnahmen sind Kubuntu, Fedora 7 und openSUSE). Sie sollten die Kopie auf den KDE-Subversion-Servern verwenden.

=== Das Kochrezept ===
cd
svn checkout svn://anonsvn.kde.org/home/kde/trunk/qt-copy
cd qt-copy
./apply_patches
./configure -qt-gif -no-exceptions -debug -fast \
-prefix $QTDIR -qdbus -pch -nomake examples \
-nomake demos
make -j2
# make install: Nur wenn QTDIR nicht das momentane Verzeichnis ist!
make install

=== Was hier passiert ===
Wir wechseln in das Heimverzeichnis des <tt>kde-devel</tt>-Benutzers (Zeile 1) und laden den Quellcode mittels Subversion (svn) herunter (Zeile 2). Nach dem Wechsel in das daraus resultierende Verzeichnis {{path|qt-copy}} (Zeile 3), führen wir ein Skript aus, das die Patches integriert, die mit <tt>qt-copy</tt> kommen (Zeile 4).

Sobald die Patches integriert sind, konfigurieren wir das build mittels des <tt>configure</tt>-Skripts (Zeilen 5-7). Die verschiedenen Kommandozeilenoptionen werden in der Datei {{path|qt-copy/README.qt-copy}} erläutert. Schließlich kompilieren wir die Mininalanforderungen für KDE (Zeile 8) und installieren Qt (Zeilen 9-10). Wenn Sie alle Beispiel- und Demo-Applikationen installieren möchten, können Sie sie entweder einzeln kompilieren oder einfach den Befehl <tt>make</tt> im Verzeichnis {{path|qt-copy}} ausführen.

Beachten Sie, dass die Installation keine root-Rechte verlangt, da Qt lokal in {{path|$QTDIR}} installiert wird. Die Installation ist ohnehin nur nötig, wenn {{path|$QTDIR}} sich von {{path|$HOME/qt-copy}} unterscheidet, was nicht der Fall ist, wenn Sie die Anweisungen exakt befolgt haben.

=== Fehlerbehebung ===
Wenn Sie die Fehlerausgabe "error: X11/Xlib.h: No such file or directory" erhalten, installieren Sie das devel-Paket von <tt>xorg</tt> (der Name des Pakets kann in verschiedenen Distributionen abweichen, in (K)Ubuntu z. B. ist er <tt>xorg-dev</tt>).

Wenn Sie eine Fehlermeldung im configure-Schritt erhalten, die auf "missing defines" hinweist, prüfen Sie den Wert von <tt>$QMAKESPEC</tt>. Manche Distributionen lassen die Variable direkt auf das standardmäßig installierte Qt verweisen. Wenn der Befehl <tt>unset QMAKESPEC</tt> das Problem löst, sollten Sie überlegen, ihn zum <tt>~/.bashrc</tt>-Skript hinzuzufügen.

Wenn Sie die Fehlermeldung ".pch/debug-shared/QtCore" erhalten, bedeutet dies, dass Qt-4.3 zwar die vorkompilierten header aktiviert hat (wenn Ihr gcc dies unterstützt), es jedoch nicht funktioniert. Wenn Sie distcc nutzen, konfigurieren Sie Qt mit der Option -no-pch. Wenn Sie icecream nutzen, führen Sie ein Update zur neuesten Version von icecream im svn trunk durch.

Versuchen Sie, irgendeine Qt-Applikation zu starten, beispielsweise {{program|assistant}}. Wenn sie in QSpanData::adjustSpanMethods abstürzt, haben Sie ein Problem mit dem Oxygen style. Versuchen Sie, {{path|lib/kde4/plugins/styles/kstyle-oxygen.so}} und {{path|lib/kde4/plugins/styles/oxygen.so}} zu entfernen, wenn sie sich im KDE-Installationspräfix finden.

== kdesupport ==

{{warning (de)|Wenn Sie diesen Abschnitt erreicht haben, ohne [[Getting_Started/Build/KDE4 (de)#Einrichten der Entwicklungsumgebung|Einrichten der Entwicklungsumgebung]] zu lesen, '''werden die hier angebotenen Rezepte nicht funktionieren'''. Diese Rezepte sind nicht defekt; <tt>cs</tt> und <tt>cb</tt> sind keine Tippfehler. Ihre Umgebung '''muss''' korrekt eingerichtet sein, damit diese Instruktionen funktionieren.}}

Es gibt eine Reihe von Bibliotheken in kdesupport, von denen andere Programme abhängen. Das umfasst Strigi und Soprano für die Datei-Metadaten und für die Suche, eigen für visuelle Effekte z.B. in Kalzium, taglib für Musik-Programme und qca für Kryptographie-Unterstützung.

Strigi selbst hat ebenfalls einige Abhängigkeiten: Sie benötigen die Bibliotheken von libz, libbz2, openssl (libcrypto oder libssl), libclucene (=0.9.16; Version 0.9.17 funktioniert '''nicht'''), und entweder libxml2 oder libexpat.

=== Das Kochrezept ===

cs # cs is kein Schreibfehler
svn checkout svn://anonsvn.kde.org/home/kde/trunk/kdesupport/
cd kdesupport
cmakekde

=== Was hier passiert ===
Wir wechseln in das Quellverzeichnis (Zeile 1), laden den Quellcode von kdesupport mittels Subversion herunter (Zeile 2) und wechseln anschließend in das neue Verzeichnis {{path|~/src/kdesupport}} (Zeile 3). Dann starten wir die Kompilierung (Zeile 4). Wir finden uns im Anschluss an die Kompilierung im build-Verzeichnis von kdesupport wieder.

=== Troubleshooting ===
Wenn Sie folgende Fehlermeldung bekommen:
CMake Error: This project requires some variables to be set,
and cmake can not find them.
Please set the following variables:
LIBXML2_INCLUDE_DIR (ADVANCED)
dann sollten Sie das Entwicklerpaket für libxml2 installieren (z.B. libxml2-devel oder ähnlich).

Wenn Sie
CMake Error: Could NOT find REDLAND
erhalten, benötigen Sie librdf aus den Redland-Bibliotheken.
Wenn Ihre Distribution das librdf-Paket nicht zur Verfügung stellt, können Sie dessen Quellcode hier herunterladen [http://download.librdf.org/source/ http://download.librdf.org/source/] und selbst kompilieren. In Gentoo heißt das Paket 'redland' anstatt librdf.

Wenn Sie
Fetching external item into 'kdesupport/admin'
Error validating server certificate for 'https://...'
erhalten, werfen Sie einen Blick auf [http://techbase.kde.org/Getting_Started/Sources/Using_Subversion_with_KDE Using Subversion with KDE]

Bei der Fehlermeldung
FILE cannot create directory: /usr/lib[64]/qt4/plugins/crypto
benötigen Sie zum Installieren des crypto-plugins Administrations-Rechte, vermutlich weil Sie die Systemweite Installation von qt4 verwenden. Am einfachsten ist es, Sie benutzen wie oben angegeben eine für den lokalen Nutzer erstellte.

== kdelibs ==
Nachdem wir Qt 4 und Strigi kompiliert haben, können wir nun mit dem Kompilieren der KDE-Basisbibliotheken fortschreiten. Wenn Sie die oben genannte Anleitung bezüglich [[Getting Started/Increased Productivity in KDE4 with Scripts/.bashrc|.bashrc]] nutzen, kommen Ihnen diese neuen Funktionen im Folgenden gelegen.

=== Das Kochrezept ===


cd $KDE_SRC
mkdir KDE && cd KDE
svn checkout svn://anonsvn.kde.org/home/kde/trunk/KDE/kdelibs
cd kdelibs
cmakekde

=== Was hier passiert ===
Wir wechseln in das KDE-Quellverzeichnis (Zeile 1), erstellen ein Verzeichnis names KDE und wechseln in dieses (Zeile 2). Dann laden wir den Quellcode der kdelibs mittels Subversion herunter (Zeile 3), wechseln in das neue Verzeichnis {{path|~/src/KDE/kdelibs}} (Zeile 4) und starten die Kompilierung (Zeile 5). Wir finden uns anschließend im <tt>kdelibs</tt>-build-Verzeichnis wieder.

{{tip|Es könnte einige fehlende Anhängigkeiten auf Ihrem System geben! Sie können in der Ausgabe von <tt>cmakekde</tt> leicht übersehen werden.
Sie können vor dem Kompilieren jeglicher KDE-Module (wie kdelibs, kdepimlibs usw.) <tt>cmake $KDE_SRC/KDE/MODULE_NAME</tt> ausführen.}}

=== Zusätzliche KDE-typische CMake-Module ===
Es gibt weitere CMake-Module in {{path|kdelibs/cmake/modules/}}, die für die Kompilierung von KDE4-Applikationen nötig sind. Sie werden mit kdelibs installiert (siehe unten).

=== Fehlerbehebung ===
Wenn Sie Schwierigkeiten bei der Kompilierung von kdelibs haben, stellen Sie sicher, dass Sie die Software im obigen Abschnitt [[Getting_Started/Build/KDE4#Required_Software|Required Software]] installiert haben und dass sie funktioniert. Andere mögliche Probleme sind:
* Wenn der Befehl <tt>cmakekde</tt> mit der Ausgabe fehlschlägt, dass CMake ein "out of source" build-Verzeichnis benötigt, entfernen Sie {{path|~/src/KDE/kdelibs/CMakeCache.txt}} und versuchen Sie es erneut.

Wenn <tt>cmakekde</tt> dennoch denselben Fehler ausgibt, versuchen Sie Folgendes:
cd
cmake -DCMAKE_INSTALL_PREFIX=$KDEDIR \
-DCMAKE_BUILD_TYPE=debugfull \
-DKDE4_BUILD_TESTS=ON \
~/src/KDE/kdelibs
make
make install
* Wenn Sie die Fehlerausgabe "Please create a separate build directory and run 'cmake path_to_kdelibs [options]' there." erhalten, müssen Sie in Ihr build-Verzechnis wechseln bevor Sie cmakekde ausführen. (z. B. <tt>cs KDE/kdelibs && cb && cmakekde</tt>)
* Wenn Qt nicht oder in einer falschen Version gefunden wird, stellen Sie sicher, dass das qmake der benötigten Qt-Version an erster Stelle (unter den qmake-Einträgen) im Pfad eingetragen ist.
* Wenn das Problem nach wie vor vorhanden ist, versuchen Sie die CMake make-Option <tt>--keep-going</tt>.
* Sie benötigen die libungif-Bibliothek, ansonsten erhalten Sie eine Fehlerausgabe ähnlich "<tt>Could NOT find GIF</tt>".
* Qt-4.3-Upgrade: Wenn Sie einen Verknüpfnugsfehler in kjsembed erhalten, der auf die QScriptEngine bezogen ist, editieren Sie CMakeCache.txt in kdelibs und entfernen Sie die Zeilen, die sich auf QT_QTUITOOLS_LIBRARY beziehen, und führen Sie den make-Befehl erneut aus (diese statische Bibliothek hat eine neue Abhängigkeit und der cmake-Code, der diese hinzufügt, benötigt sie, um ausgeführt zu werden).
* Wenn Sie die Fehlerausgabe <code>CMake Error: KDE Requires Qt to be built with SSL support</code> erhalten, installieren Sie openssl-devel, und rekompilieren Sie Qt.

== kdepimlibs ==
Sie müssen ''kdepimlibs'' nach <tt>kdelibs</tt>, aber vor ''kdebase'' installieren.

=== Das Kochrezept ===


cs KDE # [[Getting_Started/Increased_Productivity_in_KDE4_with_Scripts/.bashrc|cs ist KEIN Tippfehler]]
svn checkout svn://anonsvn.kde.org/home/kde/trunk/KDE/kdepimlibs
cd kdepimlibs
cmakekde

=== Was hier passiert ===
Wir wechseln in das KDE-Quellverzeichnis (Zeile 1), laden den Quellcode für kdepimlibs mittels Subversion herunter (Zeile 2) und wechseln anschließend in das neue Verzeichnis {{path|~/src/KDE/kdepimlibs}} (Zeile 3). Dann starten wir die Kompilierung (Zeile 4). Wir finden uns im Anschluss an die Kompilierung im build-Verzeichnis von <tt>kdepimlibs</tt> wieder.

== kdebase ==
Für manche kioslaves könnte kdebase benötigt werden.

cs KDE # [[Getting_Started/Increased_Productivity_in_KDE4_with_Scripts/.bashrc|cs ist KEIN Tippfehler]]
svn checkout svn://anonsvn.kde.org/home/kde/trunk/KDE/kdebase
cd kdebase
cmakekde

=== Fehlerbehebung ===

Wenn Sie Schwierigkeiten beim Kompilieren von kdebase haben:
* Stellen Sie sicher, dass die <tt>libxss-Header</tt> installiert sind. (Sollten diese nicht installiert sein, erhalten Sie in der Regel undefinierte Verweise auf xscreensaver-Objekte.)
* <tt>which meinproc</tt> muss {{path|/home/kde-devel/kde/bin/meinproc}} ausgeben.
* Wenn cmakekde das kdepimlibs-Verzeichnis nicht finden kann, editieren Sie die Datei {{path|$KDE_BUILD/kdebase/CMakeCache.txt}} und definieren Sie <tt>KDEPIMLIBS_INCLUDE_DIR:PATH=$KDE_BUILD/kdepimlibs</tt> manuell.
* Wenn Sie die Fehlerausgabe "Please set the following variables: X11_XTest_LIB (ADVANCED)" erhalten, installieren Sie das devel-Paket von <tt>Xtst</tt>. Auf manchen Systemen ist es separat von <tt>xext</tt> gepackt und heißt <tt>x11proto-xext-dev</tt> oder <tt>libxtst-dev</tt>. Sie müssen eventuell außerdem nach der Installation dieses Paketes die Datei CMakeCache.txt im build Verzeichnis löschen.
* Dasselbe gilt für die analoge Fehlerausgabe betreffend der Variable "X11_Xinerama_LIB (ADVANCED)": Sie benötigen das devel-Paket für <tt>xinerama</tt>.
* Wenn Sie die Fehlerausgabe "Please set the following variables: FONTCONFIG_INCLUDE_DIR, FONTCONFIG_LIBRARIES (ADVANCED)" erhalten, müssen Sie die libfontconfig-Header installieren.
* Wenn Sie die Fehlerausgabe "CMake Error: This project requires some variables to be set, and cmake can not find them. Please set the following variables: KMETADATA_LIBRARIES" erhalten, müssen Sie soprano aus kdesupport installieren und dann kdelibs neu kompilieren.
* Wenn Sie die Fehlerausgabe "‘XserverRegion’ does not name a type" erhalten, stellen Sie sicher, dass Sie die libxcomposite header installiert haben. (In Ubuntu heißen diese <tt>libxcomposite-dev</tt>.)

== Lokale API-Dokumentation erstellen ==

Obwohl die API-Dokumentation für KDE online unter [http://api.kde.org api.kde.org] verfügbar ist, kann es hilfreich sein, sie offline verfügbar zu haben, zum Beispiel wenn Sie [[Getting_Started/Set_up_KDE_4_for_development#KDevelop|KDevelop]] zum Durchsuchen der Dokumentation nutzen oder wenn Sie nicht ständig online sein können.

Seien Sie sich bewusst, dass das Generieren der API-Dokumentation mehrere Stunden in Anspruch nehmen kann und knapp ein halbes Gigabyte an Speicherplatz benötigt.
Das Generieren wird von einem Skript in {{path|kdelibs/doc/api}} ausgeführt; Sie benötigen <tt>doxygen</tt>, um es ausführen zu können.

Um die API-Dokumentation für kdelibs zu generieren, geben Sie Folgendes ein:

cs KDE/kdelibs # [[Getting_Started/Increased_Productivity_in_KDE4_with_Scripts/.bashrc|cs ist KEIN Tippfehler]]
$KDE_SRC/KDE/kdelibs/doc/api/doxygen.sh \
--doxdatadir=$KDE_SRC/KDE/kdelibs/doc/common .

Wiederholen Sie dies nach Bedarf für andere Module.

== Auf dem neusten Stand bleiben ==

Um die KDE Installation auf dem neusten Stand zu halten, sollte jedes der installierten Module regelmäßig aktualisiert werden. Da Montag der Tag mit den meisten Änderungen ist, kann Dienstag der beste Tag dazu sein. Führen Sie dazu für jedes der ausgecheckten Module, <tt>svn up</tt> und <tt>make</tt> aus.

Zum Beispiel:
<code bash>
cs kdesupport # cs is not a typo
svn up
cb # cb is not a typo
make -j2 VERBOSE=1 && make install
</code>

== Allgemeine Fehlerbehebung ==

Es kann im Laufe der Zeit nach mehrmaligem Ausführen von <tt>svn up</tt> vorkommen, dass sich das Ausgabeformat einiger Werkzeuge, die in der KDE-Werkzeugkette benutzt werden, ändert. Zum Beispiel werden <tt>kcfg</tt> Dateien vom <tt>kconfig_compiler</tt> gelesen, um die Konfigurationsdialoge zu generieren. Da CMake diese Veränderungen nicht erkennt, kann das Kompilieren fehlschlagen. Eine provisorische Lösung ist, die Regenerierung all dieser Dateien zu erzwingen:
find $KDE_SRC/kde/kdebase -name "*.kcfg" | xargs touch
Dasselbe gilt für <tt>ui</tt> Dateien wie solche, die mit Qt Designer generiert werden.

== Das war's! ==

Sie sind nun bereit, andere svn-Module in derselben Weise wie kdebase zu kompilieren, KDE 4 zu benutzen und zu testen, sowie Ihre eigenen Patches und Anwendungen zu schreiben.

Siehe auch die Anleitung [[Getting Started/Set up KDE 4 for development|Set up KDE 4 for development]] um Hilfe beim Starten von KDE-4-Anwendungen sowie zur Benutzung von KDevelop zu erhalten.

[[Category:Build KDE]]
[[Category:KDE4]]

Getting Started (de)

2008-01-18T13:27:41Z

DrSlowDecay: Changed links to german version

{{Template:I18n/Language Navigation Bar|Getting_Started}}
{{Box|Zugriff auf die Quellen|
[[Image:Action_down.svg|right|32px]]
Der KDE-Quelltext ist auf verschiedenen Wegen erhältlich:
* [[Getting Started/Sources/Anonymous SVN (de)|Anonymes SVN Schnellstart Anleitung]]
* [[Getting Started/Sources/Using Subversion with KDE|Benutzung von Subversion mit KDE]] ''Benutzung von Subversion mit KDE. Ein mehr in die Tiefe gehender Einblick für den Zugriff auf KDEs Quelltext mit Subversion, einschließlich dem Depot Layout und dem Arbeiten mit Revisionen und Patches.''
* [http://websvn.kde.org/ Durchstöbern Sie den Quelltext online]
* [[Getting Started/Sources/Snapshots|Tägliche Schnappschüsse]]
|100%}}

{{Box|Erstellung von KDE|
[[Image:Action_tool.svg|right|32px]]
Es existieren verschiedene KDE Zweige. Für den produktiven Einsatz wird eine stabile Version empfohlen.
* [[Getting Started/Build/KDE4_(de)|KDE 4 (Entwicklungs Version, Trunk)]]
* [[Getting Started/Build/Stable Version|KDE 3.5 (Stabile Version)]]
* [[Getting Started/Build|Andere Versionen und das FAQ]] ''Einschließlich Informationen für die Erstellung auf Nicht-Linux Systemen''
|100%}}

{{Box|Aufsetzen der Umgebung|
[[Image:Action_pen.svg|right|32px]]
Nachdem KDE erstellt worden ist, möchten Sie wahrscheinlich einen wirksamen Weg für das Starten der Anwendungen und das Ausführen Ihrer üblichen Entwicklungsaufgaben haben:
* [[Getting Started/Increased Productivity in KDE4 with Scripts|Erhöhen Sie Ihre Produktivität in KDE4 mit Skripten]]
* [[Getting Started/Set up KDE 4 for development (de)|Setzen Sie KDE4 für die Entwicklung auf]]
|100%}}
[[Category:Build KDE]]

Development/Tutorials/Debugging/Using Error Messages

2008-01-16T16:15:10Z

DrSlowDecay: +Language navigation

{{Template:I18n/Language_Navigation_Bar|Development/Tutorials/Debugging/Using Error Messages}}

When you start a konsole and type the commands to start an application you
will see all sorts of statements are printed in the konsole while the
application is running. All applications print these messages, to look
at them you have to know where to look. The application will have to be
compiled with the debugging enabled. So using a precompiled package from a distribution
probably will not give you this information. If you compiled the application
yourself, make sure the configure option "<tt>--disable-debug</tt>" was not used.

In KDE all debugging text-output can be switched on or off based on so
called '''areas'''. One application can be one or more area. One part of the kde base libraries can be another area. Enabling/disabling these areas from being printed can be done using the '''kdebugdialog''' application. For simple debugging selecting all
sections is probably wise.

When you are debugging it is best to simply start a konsole and start the
application from there. In a konsole you could simply type:

kicker

and in the konsole kicker could return a message like:

ERROR: kicker is already running!

When a lot of output is written to the konsole it might go out of view before
you could read it, therefor it is easy to create a text file which contains
all this information, to do so type the following:

application 2>&1 | tee debug.log

where 'application' can be replaced with the application you are debugging.
Afterwards you could open the file 'debug.log' to look at the messages again.

If you are NOT starting the application from a konsole the messages will be
logged somewhere else, or they could have been discarded by the program that
started your application.

If your application is started by clicking on an icon your best bet is to check
the following log files. Beware; they contain logs for a lot of applications,
not just the application you are debugging!

'''Case 1: Graphical login (i.e. kdm, gdm, xdm, etc.'''

The debug messages get redirected into the file {{path|~/.xsession-errors}} or
{{path|~/.X.err}} in your home directory (that is with a leading dot '.' also
watch the Capital).

'''Case 2: You are using startx:'''

Use the following command to restart your session:
startx 2>&1 | tee startx.log</pre>

so that all the debug messages of applications started at KDE's startup (and
any application launched from the panel etc.) go to the file "startx.log"

== Links ==

The debug messages are usually printed in C++ with the kDebug or kWarning statement. Example:

kDebug(1210) << "arbitrary message";
kWarning(1210) << "this rather should not happen";

The number 1210 (so called ''debug area'') in this case represents kicker. You can omit the number.

See also: [http://api.kde.org/4.0-api/kdelibs-apidocs/kdecore/html/group__kdebug.html kDebug/kWarning API documentation].

''Initial Author:'' [mailto:zander@kde.org Thomas Zander]

Development/Tutorials (de)

2008-01-16T16:07:19Z

DrSlowDecay: /* D-Bus */ -Writing mistake

{{Template:I18n/Language Navigation Bar|Development/Tutorials}}

Tutorials sind der schnellste Weg um herauszufinden, was man mit KDE anstellen kann und wie man das macht. Es folgt eine Liste der verfügbaren Tutorials '''für KDE4'''. Tutorials und Anleitungen zu KDE3 und KDE2 finden Sie am Ende dieser Seite.

== Einführung in die KDE4 Programmierung ==
Sind Sie an der Entwicklung von Programmen für KDE 4 interesiert? Wenn ja sind Sie hier genau richtig. Diese Artikelserie richtet sich an alle, die noch nie mit KDE programmiert haben.
;[[Development/Tutorials/First program (de)|Hallo Welt!]]
:''Einführung in die Grundlagen der KDE Programmierung''

;[[Development/Tutorials/Using KXmlGuiWindow (de)|Erstellen eines Hauptfensters]]
:''Dieser Artikel erklärt, wie der wichtigste Teil eines grafischen Programmes erstellt wird: das Hauptfenster.''

;[[Development/Tutorials/Using KActions (de)|Die Verwendung von KActions]]
:''In diesem Artikel erfahren Sie, wie Aktionen und Werkzeugleisten (Toolbars) im Menü hinzugefügt werden können.''

;[[Development/Tutorials/Saving and loading (de)|Laden und Speichern von Dateien]]
:''Dieser Artikel führt die KIO Bibliothek ein und erklärt wie man Dateien laden und speichern kann.''

;[[Development/Tutorials/KCmdLineArgs (de)|Befehlszeilen Argumente (todo)]]
:''In diesem Artikel werden Sie lernen Ihrer Anwendung zu ermöglichen, Dateien über die Befehlszeile oder sogar unter Dolphin mit 'Öffnen mit' zu laden''

== Grundlagen ==
;[[Development/Tutorials/KDE4 Porting Guide (de)|Ihre Applikation nach KDE 4 portieren]]
:''Anleitungen Qt3/KDE3 Applikationen nach Qt4/KDE4 zu portieren''

;[[Development/Tutorials/CMake (de)|Einführung in CMake]]
:''Wie man CMake in KDE 4 benutzt''

;[[Development/Tutorials/Common Programming Mistakes (de)|Häufige Programmierfehler]]
:''Einige häufige Fehler die man während der Entwicklung von Qt und KDE Applikationen machen kann und wie man sie vermeidet.''

;[[Development/Tutorials/Using Qt Designer (de)|Den Qt Designer benutzen um Benutzerschnittstellen zu erzeugen]]
:''Wie man UI Dateien mit dem Designer erzeugt und wie man diese in einem KDE Programm integriert.''

== Testen und Fehler beheben ==

;[[Development/Tutorials/Debugging (de)|Debugging Ihrer Applikation]]
:''Tips, Tools und Techniken zum Debuggen von KDE Applikationen''

;[[Development/Tutorials/Unittests|Schreiben von Unit-Tests für Qt4 und KDE4 mit QTestLib]] ([http://developer.kde.org/documentation/tutorials/writingunittests/writingunittests.html Original link])
:''Tutorial von [mailto:bradh@frogmouth.net Brad Hards] das beschreibt, wie man Unit-Tests mit dem QTestLib Framework erstellt. Das Tutorial wird anhand eines Beispiels beschrieben und befindet sich zur Zeit noch in Entwicklung.''

;[[Development/Tutorials/Code_Checking|Halbautomatische Werge zur Erkennung von Programmierfehlern]]
:''Techniken um Fehler in KDE Code aufzuspüren''

== Konfigurationen mit KConfig verwalten ==
;[[Development/Tutorials/KConfig|Einführung in KConfig]]
:''Eine Übersicht über die zu KConfig gehörenden Klassen und wie Sie diese in Ihre Anwendung einbinden können''

;[[Development/Tutorials/Using KConfig XT|Benutzung von KConfig XT]]
:''Tutorial über das effiziente Benutzen des KConfig XT Frameworks.''

;[[Development/Tutorials/Updating KConfig Files|Update von KConfig Dateien]]
:''Tutorial das beschreibt, wie man ein Update-Skript erstellt, dass Veränderungen am Format der Konfiguration Ihrer Anwendung mit den bereits vorgenommenen Einstellungen des Anwenders abgleicht.''

== Dienste: Applikationen und Plugins ==
;[[Development/Tutorials/Services/Introduction (de)|Einführung in das Dienst-Framework]]
:''Eine Einführung über das Dienst-Framework in KDE und was es dem Applikationsentwickler zur Verfügung stellen kann. Beschäftigt sich mit dem system configuration cache (SyCoCa), den benötigten Dateien und wie indizierte Informationen benutzt werden.

;[[Development/Tutorials/Services/Traders (de)|Dienste über Trader Queries finden]]
:''Wie man mit der Trader Query Syntax Dienste wie Plugins oder Mimetypes findet, die im SyCoCa zwischengespeichert wurden. ''

;[[Development/Tutorials/Services/Plugins|Erstellen und Laden von Plugins mit KService]]
:''Zeigt, wie man eigene Plugintypen definiert, installiere Plugins findet (einschließlich denen von anderen Herstellern) und wie man diese einfach und portabel läd, indem man KService benutzt.''

== Lokalisierung ==
;[[Development/Tutorials/Localization/Unicode (de)|Einführung in Unicode]]
:''Eine Einführung was Unicode ist und wie KDE Applikationen damit umgehen.''

; [[Development/Tutorials/Localization/i18n (de)|Beim Schreiben der Applikation an die Lokalisierung denken]]
:''Diese Anleitung beschäftigt sich damit, was Lokalisation ist, warum sie wichtig ist und wie man sicherstellt, dass die eigene Applikation bereit ist, lokalisiert zu werden. Jeder Applikationsentwickler sollte das lesen.''

; [[Development/Tutorials/Localization/i18n Mistakes (de)|Häufige Fehler vermeiden]]
:''Es gibt einige häufige Fehler, die es verhindern, dass eine Applikation angemesssen übersetzt werden kann. Diese Anleitung zeigt diese Fehler auf und zeigt, wie man sie vermeidet.''

; [[Development/Tutorials/Localization/Building KDE's l10n Module|Erstellen von KDE's Lokalisierungs Modul]]
:''Das Erstellen und Installieren der Sprachunterstützung mit KDE's Lokalisierungs-Modul (l10n) ist ratsam für alle, die an Anwendungen im KDE Haupt-Repository arbeiten. Hierdurch erreichen Sie, das Sie Ihre Anwendung in anderen Sprachen testen und somit auftauchende Probleme erkennen können. Dieses Tutorial bringt Ihnen genau das bei.''

; [[Development/Tutorials/Localization/i18n Build Systems|Einbeziehen von i18n in das Build System]]
:''Sobald Ihre Anwendung bereit dazu ist lokalisiert zu werden, ist es der nächste Schritt sicherzustellen, dass die Übersetzungsdateien automatisch erstellt und aktuell gehalten werden. Dieses Tutorial behandelt die nötigen Änderungen an den CMakeFile.txt Dateien sowie den Prozess um den resultierenden Nachrichten-Katalog mit Ihrer Applikation zu verteilen.''

; [[Development/Tutorials/Localization/i18n Challenges|i18n - Herausforderungen and Lösungen]]
:''Dieses Tutorial behandelt die Aufgaben und Fallstricke, die bei der Lokalisierung auftreten wie das Übersetzen von Handbüchern und anderen Daten die ausserhalb des Quellcodes auftreten, das Behandeln von nicht mehr gültigen .po-Dateien, das Umgehen mit Freezes, programmieren in anderen Sprachen als Englisch und Erstellung unabhängiger Releases oder das Verschieben von Anwendungen zwischen KDE Modulen.''

; [[Development/Tutorials/Localization/i18n_Semantics|Semantisches Markup für Nachrichten]]
:''Um eine konsistente und semantisch korrekte Darstellung von Nachrichten in Anwendungen sicherzustellen, können semantische Kommentare zu den Nachrichten, die übersetzt werden sollen, mit dem KUIT System hinzugefügt werden. Dieses Tutorial beschreibt die Funktionsweise dieses Systems.''

; [[Development/Tutorials/Localization/i18n Krazy|Automatisierte i18n Codeüberprüfung]]
:''Der Krazy Code-Checker durchsucht KDE's Code und meldet häufige i18n Fehler.''

; [[Development/Tutorials/Localization/Language Change (de)|Mit Sprachänderungen umgehen]]
:''Wie man seiner Applikation beibringt beim nächsten Start oder zur Laufzeit eine andere Sprache zu benutzen.''

== Dokumentation ==

;[[Development/Tutorials/API_Documentation|API Dokumentation]]
:''Dieses Tutorial erklärt, wie Sie Ihre APIs korrekt dokumentieren.''

;[[Development/Tutorials/Man_Pages|Man Seiten]]
:''Das Schreiben und Erstellen von Referenz-Handbüchern.''

== Anwendungsautomatisierung und Skripting ==

=== D-Bus ===
; [[Development/Tutorials/D-Bus/Introduction|Einführung in D-Bus]]
:''Eine unkomplizierte Einführung in die Kernkonzepte von D-Bus aus der Sicht eines Anwendungs-Programmierers. Dieses Tutorial behandet was D-Bus ist, und wie Sie es in Ihren Anwendungen einsetzen können.''

; [[Development/Tutorials/D-Bus/Accessing Interfaces|Zugriff auf D-Bus Schnittstellen]]
:''Eine Schrittweise Anleitung zum Aufruf von D-Bus-Methoden und zur Verbindung mit D-Bus-Signalen unter Verwendung von QtDBus.''

; [[Development/Tutorials/D-Bus/Intermediate_D-Bus|D-Bus für Fortgeschrittene]]
:''Tips zur Verwendung von QtDBus wenn sie mit problematischen Realwelt-Schnittstellen konfrontiert werden.''

; [[Development/Tutorials/D-Bus/Creating Interfaces|Erstellen von D-Bus Schnittstellen]]
:''Lernen Sie, wie sie Funktionalität Ihrer Applikationen bereit stellen, indem Sie eigene D-Bus Schnittstellen erstellen und benutzen. Beschreibt das Erstellen von XML-Beschreibungen, die Bereitstellung von Schnittstellen zur Laufzeit und das Aufsetzen des Build-Systems mit CMake.''

; [[Development/Tutorials/D-Bus/Autostart Services|D-Bus Autostart Dienste]]
:''Machen Sie mit diesem Tutorial aus Ihrer Anwendung einen D-Bus-Autostart-Dienst. Dieses Feature, dass auch als "D-Bus Dienst Aktivierung" bekannt ist, ermöglicht es, dass D-Bus Aufrufe zu Ihrer Applikation selbst dann funktionieren, wenn sie gerade nicht läuft indem sie den D-Bus-Daemon Ihre Applikation starten lassen, wenn deren Funktionen benötigt werden.''

; [[Development/Tutorials/Porting_to_D-Bus|Portieren von DCOP nach D-Bus]]
: ''Portieren Sie mit Hilfe dieser Anleitung Ihre Anwendungen von DCOP nach D-Bus.''

=== Konqueror ===
; [[Development/Tutorials/Creating Konqueror Service Menus|Erstellung von Konqueror Dienstmenus]]
:''Dieses Tutorial zeigt Ihnen wie Sie MIME-Typ-spezifische Aktionen in Konquerors Kontextmenu bereitstellen.''

=== Kross ===
; [[Development/Tutorials/Kross/Introduction|Einführung in Kross]]
:''Eine Einführung in das Kross Scripting Framework.''

; [[Development/Tutorials/Kross/Hello_World|Hallo Welt]]
:''Eine erste Anwendung mit funktionierendem Kross Code.''

; [[Development/Tutorials/Kross/Connecting_Signals_and_slots_in_Kross|Verbinden von Signalen und Slots in Kross]]
:''Einfache Demonstration, wie man Signale von Objekten mit Slots von Skripten verbindet.''

; [[Development/Tutorials/Kross/Scripts-as-Plugins|Skripte als Plugins mit Kross]]
:''Dieses Tutorial bietet eine schrittweise Einführung, wie Sie Skripte als Plugins in eine KDE Anwendung integrieren.''

=== KOffice ===
; [[Development/Tutorials/KOffice Overview|KOffice Übersicht]]
:''Dieses Dokument zeigt eine Übersicht über die verschiedenen KOffice Plugin Typen sowie ihren jeweiligen Nutzen und Stärken.'' Wenn KOffice Plugins neu für Sie sind, ist dieses Tutorial für Sie geeignet.

; [[Development/Tutorials/Write a Flake Plugin|Erstellen von KOffice Flake Plugins]]
:''Dieses Tutorial zeigt Ihnen wie Sie ein Plugin für KOffice Anwendungen erstellen das Ihnen mit Hilfe von Flake erlaubt, Inhalte in ODF-Dokumente einzubetten.''

; [[Development/Tutorials/KWord Scripting|KWord Scripting]]
:''Dieses Tutorial zeigt, wie man KWord mit Skriptsprachen wie Python, Ruby oder JavaScript über Kross anspricht.''

; [[Development/Tutorials/KSpread Scripting|KSpread Scripting]]
:''Dieses Tutorial zeigt, wie man KSpread mit Skriptsprachen wie Python, Ruby oder JavaScript über Kross anspricht.''

; [[Development/Tutorials/Krita Scripting|Krita Scripting]]
:''Dieses Tutorial zeigt, wie man Krita mit Skriptsprachen wie Python, Ruby oder JavaScript über Kross anspricht.''

=== SuperKaramba ===
; [[Development/Tutorials/SuperKaramba|SuperKaramba Tutorial]]
:''Dieses Tutorial bietet einen Einblick in SuperKaramba, Themen-Dateien und das Skripten mit Python, Ruby und JavaScript.

== Suche und Meta-Daten ==

=== Strigi ===

; [[Development/Tutorials/Writing file analyzers|Schreiben von Datei-Analysierern]]
:''Datei-Analysierer extrahieren Daten aus Dateien um Sie in Datei-Dialogen und Datei-Managern anzeigen können. Die Daten die auf diesem Weg erhalten werden, werden auch für die Suche nach Dateien verwendet. KDE4 erlaubt die Benutzung von mehreren Analysierern pro Dateityp. Dieses Tutorial beschreibt, wie Sie neue Analysierer schreiben können.''

=== Nepomuk ===

; [[Development/Tutorials/Metadata/KMetaData first steps|Erste Schritte mit Nepomuk]]
:''Nepomuk ist die KDE-Bibliothek die einfachen Zugriff auf Metadaten im [http://nepomuk-kde.semanticdesktop.org Nepomuk-KDE] System erlaubt. Lernen Sie, wie Ihre Applikation mit Hilfe von Nepomuk Metadaten bereitstellen und verwenden kann.''

== Ansprechen von Hardware (Solid) ==

;[[Development/Tutorials/Solid_Tutorials|Einführung in Solid]]
:''Eine Einführung in die Benutzung der Solid Hardware-Erkennung und -Verwendung in KDE Applikationen.''

;[[Development/Tutorials/Solid_Network_Tutorial|Zugriff auf Netzwerk-Informationen]]
:''Wie man Solid benutzt um Informationen über das Netzwerk herauszufinden''

== Multimedia (Phonon) ==

;[[Development/Tutorials/Phonon/Introduction|Phonon]]
:''Erste Schritte mit der Multimedia API''

:''Erstellung und Benutzung von Phonon und seinem GStreamer Backend unter Linux mit Qt 4.3.x''
::''Dieser Artikel gibt Ihnen eine kurze Anleitung wie Sie Phonon und sein GStreamer Backend unter GNU/Linux mit lediglich Qt 4.3.x beziehen, kompilieren und benutzen können. Gegen Ende beschreibt der Artikel zusätzlich, wie ein Entwickler Phonon benutzen kann um einfache Audio- und Video-Spieler zu erstellen. Sie können den Artikel [http://www.vcreatelogic.com/oss/docs/CompilingPhononOnLinux.pdf hier] lesen.
Sie können die editierbare OpenDocumentText Datei von [http://www.prashanthudupa.com/phonon/CompilingPhononOnLinux.odt hier]. herunterladen''

== Plasma ==

;[[Development/Tutorials/Plasma/GettingStarted|Erste Schritte mit Plasmoids]]
:''Erstellung Ihres ersten Plasma-Widgets oder Plasmoids in C++ mit einem SVG Hintergrund, einem Icon und etwas Text''

;[[Development/Tutorials/Plasma/DataEngines|Schreiben einer DataEngine]]
:''DataEngines bieten eine standardisierte Schnittstelle zur Darstellung von Daten aus verschiedenen Datenquellen. Lernen Sie was eine DataEngine ist und wie Sie selbst ein schreiben können.''

;[[Development/Tutorials/Plasma/UsingDataEngines|Benutzung von DataEngines in Plasmoids]]
:''Mit einer DataEngine ist es möglich, Daten auf einfache und standardisierte Art und Weise zu empfangen und darzustellen. Dieses Tutorial behandelt das Thema, wie man DataEngines zu diesem Zweck in Plasma einsetzt.''

;[[Development/Tutorials/Plasma/AbstractRunner|Erstellen von Runners]]
:''Runners sind Plugins die Aktions-basierte Suchfunkionalität im Plasma Ausführen-Dialog erlauben. Diese Plugins können von jeder Applikation verwendet werden, die libplasma einbindet.''

== Kate / Kwrite ==

;[[Development/Tutorials/Kate/KTextEditor Plugins|Erste Schritte mit KTextEditor Plugins]]
:''Erstellung Ihres ersten KTextEditor Plugins''

== Drucken ==

;[[Development/Tutorials/Printing Hello World|Hallo Welt]]
:''Einführung in das KDE Drucksystem''

;[[Development/Tutorials/Printing Print Dialog|Druckdialog]]
:''Benutzung des KDE Druckdialogs''

== Neue Dinge herunterladen ==
; [[Development/Tutorials/Introduction to Get Hot New Stuff|Einführung in "Neue Dinge herunterladen"]]
:''Eine Einführung in das Entwickler-freundliche Netzwerk-Update-System das KDE Applikationen erlaubt, neue Anwendungsdaten zur Laufzeit auf benutzerfreundliche Weise herunterzuladen.''

;[[Development/Tutorials/KNewStuffSecure|Sicherheit mit KNewStuff]] ([http://developer.kde.org/documentation/tutorials/knewstuffsecure/index.html Original Link])
:''Tutorial das zeigt, wie man Ressourcen auf sichere Weise teilt (KDE 3.4 und später).'' Geschrieben von András Mantia <amantia@kde.org>.

== Schnelle Anwendungsentwicklung ==

=== Python ===

;[[Development/Tutorials/Python introduction to signals and slots|101 Einführung in Signale und Slots]]
:''Eine einfache Einführung in Qt's Signal- und Slot-Architektur.''

=== Ruby ===

;[http://developer.kde.org/language-bindings/ruby/kde3tutorial/index.html KDE Ruby Korundum Tutorial]
:''Eine Ruby-Version von Antonio Larossa Jiménezs KDE Tutorial von Richard Dale. Sehen Sie sich for Qt Tutorials und andere Informationen auch die [http://developer.kde.org/language-bindings/ruby/index.html Ruby Developers Corner] an.''

;[[Development/Tutorials/Qt4_Ruby_Tutorial|Qt4 Ruby Tutorial]]
:''Trolltechs sagenhaftes Einstiegstutorial in Qt, übersetzt für Ruby.''

=== Shell ===

;[[Development/Tutorials/Shell_Scripting_with_KDE_Dialogs|Shell Scripting mit KDE Dialogen]] ([http://developer.kde.org/documentation/tutorials/kdialog/t1.html Original Link])
:''Tutorial von [mailto:bradh@frogmouth.net Brad Hards] das beschreibt, wie man KDE Dialoge mit Hilfe von kdialog in Shell-Skripten verwendet. Das Tutorial wird anhand eines Beispiels durchgeführt.''

== Andere Tutorials ==

=== Benutzung der KDE Games Bibliothek ===
;[[Development/Tutorials/Games/KStandardGameAction| KStandardGameAction]]
:''Benutzung von libkdegames um Ihr Spiel dem kdegames Standard anzupassen''
;[[Development/Tutorials/Games/Highscores| Highscores]]
:''Implementierung einer einfachen Highscore-Tabelle in Ihrem Spiel''
;[[Development/Tutorials/Games/Theme Selector| Themen-Auswahl]]
:'' Benutzung des libkdegames Themen-Auswahl-Dialogs''

=== 2D Plotting (KPlotWidget) ===
;[[Development/Tutorials/KPlotWidget|Benutzen des KDE Daten-Plotting Widgets]]
:''Dieses Tutorial führt KPlotWidget ein, welches zum plotten zweidimensionaler Daten verwendet werden kann. Es enthält Informationen zu einfachen Benutzung des Widgets (inklusive Hinzufügen und Änderung von Datensätzen sowie Anpassung der Koordinatenachsen und deren Beschriftung) sowie erweiterten Anwendungsfällen (inklusive Erweiterung des Widgets durch Vererbung).''

=== Rechtschreib- und Grammatikprüfung (Sonnet) ===
;[[Development/Tutorials/Sonnet/SonnetTutorial|Rechtschreib- oder Grammatikprüfung in KDE Applikationen einbinden]]
:''Diess Tutorial führt in Sonnet ein und wie man es benutzt um Sprachkorrekturen in der eigenen KDE Anwendung zu verwenden. Sonnets Hilffunktionen sollen in einem weiteren Tutorial beschrieben werden.''

=== Pixmap cache (KPixmapCache) ===
;[[Development/Tutorials/KPixmapCache|Benutzung des KDE Pixmap Caches]]
:''Dieses Tutorial demonstriert die Benutzung von KPixmapCache zum Zwischenspeichern von beispielsweise Pixmaps die aus SVGs oder Daten erstellt wurden.''

== Material für KDE2 und KDE3 ==

;[[Development/Tutorials/KDE3|KDE3 Tutorials]]
:''Diese Tutorials behandeln Themen im Bezug auf KDE3.''

;[[Development/Tutorials/KDE2|KDE2 Tutorials]]
:''Diese Tutorials behandeln Themen im Bezug auf KDE2.''

[[Category:KDE4]]

Template:TutorialBrowser (de)

2008-01-16T10:08:15Z

DrSlowDecay: Added a link to german start page

<div class="rbroundbox" style="width:100%;">
<div class="rbtopwrap">
<div class="rbtop"><div></div></div>{{{name}}}</div>
<div class="rbcontent">
{|style="width:100%; background:#dadde0;"
|-
| width=25% align=right valign=top | '''Anleitungsserie'''  
| {{{series|n/a}}}
|-
| align=right valign=top | '''Voriges Kapitel'''  
| {{{pre|None}}}
|-
| align=right valign=top | '''Nächstes Kapitel'''  
| {{{next|n/a}}}
|-
| align=right valign=top | '''Weiterführende Texte'''  
|{{{reading|n/a}}}
|-
| align=right valign=top | '''Navigation'''  
|[[Welcome to KDE TechBase (de)|Deutsche Startseite]]{{{otherlinks|}}}
|}
</div>
<div class="rbbot"><div></div></div>
</div>
{{DISPLAYTITLE:{{{name}}}}}
[[Category:Tutorial (de)]]<noinclude>

==Empfohlene Benutzung==
Um im Wiki eine gewisse Konsistenz zu behalten: Wird diese Vorlage benutzt, sollte sie auf der Seite ganz oben eingefügt werden und zwar über jeder ==Überschrift==, damit die Informationen für den Leser möglichst schnell zugänglich sind.

Weiterhin fügt diese Vorlage automatisch an das Ende der Seite eine [[:Category:Tutorial (de)|Anleitungskategorie]], daher besteht keine Veranlassung das von Hand zu machen.

==Parameters==

{| class="wikitable"
|-
! Parameter !! Function
|-
| '''series''' || Die Serie von Anleitungen zu der diese Anleitung gehört
|-
| '''name''' || Beschreibender Name dieses Kapitels.
|-
| '''pre''' || Vorausgehende Kapitel, die gelesen sein sollten (versuche sie vernünftig zu ordnen und stelle sicher, dass es sich um Links handelt)
|-
| '''next''' || Die Anleitung, die logisch auf diese hier folgt (aus der gleichen Serie). Oder eine Anleitung mit der es Sinn macht, als nächstes fortzufahren.
|-
| '''reading''' || Weitere Texte, die das entsprechende Thema vertiefen
|-
| '''otherlinks''' || Weitere allgemeine Links zu übergeordneten Kapiteln
|-
|}

[[Category:Template]]
</noinclude>

Getting Started/Sources/Anonymous SVN (de)

2008-01-16T08:38:55Z

DrSlowDecay: Added language navigation bar + german templates

{{Template:I18n/Language Navigation Bar|Getting Started/Sources/Anonymous SVN}}

== Zusammenfassung ==

Für diejenigen von uns, welche bei der vordersten Front mitarbeiten wollen, gibt es einen einfachen Weg, eine aktuelle lokale Kopie des KDE Source Codes auf dem Rechner zu haben - anonymous SVN.

Bitte beachten Sie, dass einige Linux Distributoren schon die KDE SVN Pakete beilegen, '''damit brauchen Sie nicht unbedingt Qt und KDE selber zu kompilieren! '''
Lesen Sie dazu [[Getting_Started/Distribution_Packages]] für Anleitungen und Informationen.

== Anonymous SVN ==

=== Subversion einrichten===
Als aller ersten müssen Sie die Subversion-Binarys installieren, falls diese noch nicht auf ihrem Computer vorhanden sind.
Sehr wahrscheinlich wird für Ihr Betriebssystem ein Packet dazu vorhanden sein. Falls nicht, können Sie es selber von der [http://subversion.tigris.org/project_packages.html SVN-Projektpage herunterladen] und übersetzten (Kompilieren).
Bitte lesen die [[Getting_Started/Sources/Using_Subversion_with_KDE|KDE Subversion tutorial]], wenn Sie sich dafür interessieren wie SVN funktioniert.

=== Checkout KDE ===

'''/trunk/''' ist der Pfad in welchem das Qt4-basierende KDE 4 entwickelt wird.
Folgende sind die wichtigsten Befehle, welche Sie brauchen um KDE aus SVN aus zu checken und zu Kompilieren:

svn co svn://anonsvn.kde.org/home/kde/trunk/KDE/kdelibs
svn co svn://anonsvn.kde.org/home/kde/trunk/KDE/kdebase

{{tip|Verwenden Sie "'''svn co'''" nur für das erst Checkout; später werden Sie "'''svn up''' ''modulename''" oder "'''svn update''' ''modulename''" verwenden um die Verzeichnisse auf den neusten Stand zu bringen.}}

{{tip|Sollte ihre Firewall den Zugriff auf die Ports verweigern, können Sie '''svn://anonsvn.kde.org/'''durch '''svn://websvn.kde.org:443/''' ersetzen.}}

'''qt-copy''' is a copy of the latest stable [http://www.trolltech.com Qt] release which works with KDE, put into SVN for convenience. It also contains patches by KDE developers that haven't found their way to Qt yet. They are recommended for those working with KDE from '''trunk'''. You can obtain '''qt-copy''' by doing:

svn co svn://anonsvn.kde.org/home/kde/trunk/qt-copy

If you wish to have a complete copy of the KDE distribution, you can simply check out the entire source tree with one command:

svn co svn://anonsvn.kde.org/home/kde/trunk/KDE

{{note (de)|It is smarter to first use [http://websvn.kde.org/trunk/KDE The KDE Source Repository Web Viewer]. Use it to choose which modules to download. This way KDE will be quicker to install and try out.}}

If you want additional software packages you can check out the following modules within '''trunk/''' as well:

koffice
extragear
playground
kdereview

So, for example, if you want to check out koffice trunk, you can use

svn co svn://anonsvn.kde.org/home/kde/trunk/koffice

=== Checking out trunk using snapshots ===

If you are checking out modules from '''trunk/''' you may be able to save time by using snapshots. Using Subversion trunk snapshots is described at [[../Snapshots|the Subversion snapshots tutorial page]].

=== Checking out KDE 3 instead ===

If you want to track KDE 3 rather than the bleeding edge, you may retrieve the KDE 3.5 sources using:

svn co svn://anonsvn.kde.org/home/kde/branches/arts/1.5/arts
svn co svn://anonsvn.kde.org/home/kde/branches/KDE/3.5/

And if you want the matching qt-copy:
svn co svn://anonsvn.kde.org/home/kde/branches/qt/3.3/qt-copy

=== Checking out specific releases ===

KDE modules are also tagged at each release so that it is possible to get a specific release of KDE. Most KDE modules have a tag name in the format '''tags/KDE/X.Y.Z''' (where X, Y and Z represent the exact version). The arts module (only needed for KDE 2 and KDE 3) has a different format of tag name, '''tags/arts/X.Y.Z'''. For instance to get kdelibs as it was shipped in KDE 3.5.0, do:

svn co svn://anonsvn.kde.org/home/kde/tags/KDE/3.5.0/kdelibs/

If you then want to update this checkout to KDE 3.5.5, use this command:

svn switch svn://anonsvn.kde.org/home/kde/tags/KDE/3.5.5/kdelibs

{{tip|If you used a '''/branch/''' or '''/trunk/''' path, then there is no need to switch, just run '''svn update'''.}}

{{tip|[http://websvn.kde.org/tags/ WebSVN] is a convenient way to check for a tag name.}}

=== Checking out translations ===
If you are looking for translations and other localizations, check out the appropriate language from the [http://websvn.kde.org/trunk/l10n l10n] module.

{{Warning (de)|The l10n module is ''extremely'' large. Be sure you have lots of time and disk space on hand before checking out the entire l10n module. Most people only check out specific language subdirectories rather than the entire l10n module.}}

Getting Started (de)

2008-01-16T08:35:57Z

DrSlowDecay: Changed link to german version

{{Template:I18n/Language Navigation Bar|Getting_Started}}
{{Box|Zugriff auf die Quellen|
[[Image:Action_down.svg|right|32px]]
Der KDE-Quelltext ist auf verschiedenen Wegen erhältlich:
* [[Getting Started/Sources/Anonymous SVN (de)|Anonymes SVN Schnellstart Anleitung]]
* [[Getting Started/Sources/Using Subversion with KDE|Benutzung von Subversion mit KDE]] ''Benutzung von Subversion mit KDE. Ein mehr in die Tiefe gehender Einblick für den Zugriff auf KDEs Quelltext mit Subversion, einschließlich dem Depot Layout und dem Arbeiten mit Revisionen und Patches.''
* [http://websvn.kde.org/ Durchstöbern Sie den Quelltext online]
* [[Getting Started/Sources/Snapshots|Tägliche Schnappschüsse]]
|100%}}

{{Box|Erstellung von KDE|
[[Image:Action_tool.svg|right|32px]]
Es existieren verschiedene KDE Zweige. Für den produktiven Einsatz wird eine stabile Version empfohlen.
* [[Getting Started/Build/KDE4_(de)|KDE 4 (Entwicklungs Version, Trunk)]]
* [[Getting Started/Build/Stable Version|KDE 3.5 (Stabile Version)]]
* [[Getting Started/Build|Andere Versionen und das FAQ]] ''Einschließlich Informationen für die Erstellung auf Nicht-Linux Systemen''
|100%}}

{{Box|Aufsetzen der Umgebung|
[[Image:Action_pen.svg|right|32px]]
Nachdem KDE erstellt worden ist, möchten Sie wahrscheinlich einen wirksamen Weg für das Starten der Anwendungen und das Ausführen Ihrer üblichen Entwicklungsaufgaben haben:
* [[Getting Started/Increased Productivity in KDE4 with Scripts|Erhöhen Sie Ihre Produktivität in KDE4 mit Skripten]]
* [[Getting Started/Set up KDE 4 for development|Setzen Sie KDE4 für die Entwicklung auf]]
|100%}}
[[Category:Build KDE]]

Getting Started/Sources/Subversion

2008-01-16T08:34:33Z

DrSlowDecay: Added language navigation

{{Template:I18n/Language Navigation Bar|Getting Started/Sources/Using Subversion with KDE}}

{{TutorialBrowser|

series=Getting Started|

name=Using Subversion With KDE|
}}

== Abstract ==

This is a quick KDE-specific introduction for using subversion to access files and software in KDE's repositories. For comprehensive coverage of Subversion we recommend reading the book
"[http://svnbook.red-bean.com/ Version Control with Subversion]".

== Getting started ==

In order to use the KDE Subversion repository, you will need two things:

# A Subversion client program
# An account in our repository

Note: For anonymous read-only access use protocol "svn", no "yourname@" and server "anonsvn.kde.org" instead below.

'''Installing Subversion:''' instructions on installing the client are not
presented here. Refer to your system installation instructions to find out how
you can install Subversion. You will need version 1.1 at least. If you are
compiling from sources and want to access the KDE repository by https
(and not by svn+ssh), you will need SSL and ZLIB support,
so you will need the <tt>--with-ssl --with-zlib</tt> options.

Alternatively, you can install one of the many graphical clients out there.
This tutorial is intended for people using the <tt>svn</tt> program only, referring
to tasks accomplished with the usual <tt>cvs</tt> program.

'''Getting an account:''' if you had a CVS
account before, it has been migrated to the new Subversion client. If
you didn't, refer to the [[Contribute/Get_a_SVN_Account|corresponding tutorial]] how to get one.

{{Note|If you have lost your CVS password, there are simple ways to retrieve
it. Use [http://ktown.kde.org/~coolo/cvspwd.c cvspwd.c] or [http://kdab.net/~dfaure/cvs-unscramble cvs-unscramble] (Perl).}}

== The KDE repository structure ==

svn.kde.org/home/kde

That's the address of the KDE Subversion repository. The repository is served by
HTTPS or SVN+SSH protocol, which means your password is secure against third-party
eavesdropping.

The SSL certificate md5 fingerprint for the repositories:
F6BF EDE2 D016 D1B2 4F18 742E 2C8F B7EF

The SSL certificate sha1 fingerprint for the repositories:
e1:e6:41:96:3c:eb:ae:78:e2:73:0d:a2:32:2f:6b:21:13:bf:3d:0f

For people using svn+ssh, here's the fingerprint of the server's RSA key:
86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb

The repository is organised in main directories:

# /branches
# /tags
# /trunk

You can explore the repository structure at [http://websvn.kde.org/ http://websvn.kde.org/]

=== The top-level directory /trunk ===

The <tt>/trunk</tt>
top-level subdirectory is where the main development for KDE occurs.
What you will find here is what will become the next KDE release, and
its associated programs. Here you will also find the <tt>www</tt> module,
which contains webpages for KDE's site and related ones.

<tt>/trunk</tt> is further subdivided into these sub-directories:

*<tt>KDE/</tt> KDE itself, what will become the next public release. It contains the following modules:
**'''kdelibs''' - KDE basic libraries, used by all KDE programs
**'''kdebase''' - KDE base programs, like the KDE Control Center, Kicker (the panel) and Konqueror (the web browser)
**'''kdeaccessibility''' - Accessibility files
**'''kdeadmin''' - KDE Administration applications
**'''kdeartwork''' - Images, themes, sounds and other art files
**'''kdebindings''' - Bindings for languages other than C++
**'''kdeedu''' - KDE Educational applications
**'''kdegames''' - KDE Games
**'''kdegraphics''' - KDE Graphical applications
**'''kdemultimedia''' - KDE Multimedia applications
**'''kdenetwork''' - KDE Networking applications
**'''kdepim''' - KDE Personal Information Management applications
**'''kdepimlibs''' - Libraries used by KDE-PIM applications.
**'''kdesdk''' - KDE Software Development Kit applications
**'''kdetoys''' - KDE toy applications
**'''kdeutils''' - KDE General utilities
**'''kdevelop''' - The KDevelop program
**'''kdevplatform''' - The development platform which KDevelop is based on
**'''kdewebdev''' - KDE Web development applications
*<tt>kde-common</tt>
:Common admin/ directory
*<tt>bugs/</tt>
:[http://bugs.kde.org/ Bugzilla] files
*<tt>developer.kde.org/</tt>
:The content of developer.kde.org
*<tt>extragear/</tt>
:KDE programs outside the main KDE releases.
*<tt>kdereview/</tt>
:Temporary home for KDE applications that are believed to have reached release-quality. From here, once all major issues are resolved, applications are moved either to <tt>/trunk/KDE/</tt> or to <tt>/trunk/extragear/</tt>
*<tt>kdesupport/</tt>
:Supporting applications and libraries for KDE
*<tt>koffice/</tt> The KDE Office suite, containing the programs:
**'''karbon'''
**'''kchart'''
**'''kexi'''
**'''kformula'''
**'''kivio'''
**'''koshell'''
**'''kplato'''
**'''kpresenter'''
**'''krita'''
**'''kspread'''
**'''kugar'''
**'''kword'''
*<tt>konstruct/</tt>
:Konstruct, the KDE build program
*<tt>l10n-kde3/</tt>
:Translations for the "unstable" modules of KDE 3 (extragear, playground)
*<tt>l10n-kde4/</tt>
:Translations for KDE 4
*<tt>playground/</tt>
:The KDE playground: applications being developed, but not having yet reached release-quality.
*<tt>qt-copy/</tt>
:The convenience copy of [http://www.trolltech.com/ Trolltech's] Qt library, which KDE is based upon.
*<tt>tests/</tt>
:khtml, KOffice and ksvg testcases
*<tt>valgrind/</tt>
:The Valgrind application, which is hosted on the KDE repository, but that is not part of KDE itself. Note that newer versions of Valgrind are developed on their own repository. The KDE Valgrind modules only holds up to Valgrind 2.4.
*<tt>www/</tt>
:Webpages for the KDE site (and related sites). Write access to this directory is restricted.

=== The top-level directory <tt>/tags</tt> ===

This
directory contains the official releases of the programs maintained and
developed in the KDE repository. Each individual application has a
subdirectory here. Inside it, you will find the release numbers.

For instance, the KDE 3.4.0 code can be found under <tt>/tags/KDE/3.4.0/</tt>.

=== The top-level directory <tt>/branches</tt> ===

This directory contains the branch versions of the applications after a major release.

Most
KDE applications adhere to the philosphy that new features (as well as
new user-visible strings) are added only to the next release cycle —
the one that lives in <tt>/trunk/</tt>. However, bugfixes are applied to all
applications, even after release.

In
order to do that, a branch is created at the moment of the release,
indicating the state of the files at that time. Bugfixes are then
checked in to those files. Those branches are the ones in <tt>/branches/</tt>.

For instance, the KDE 3.4.x branch can be found under <tt>/branches/KDE/3.4/</tt>

The subdirectories you will find inside <tt>/branches</tt> are the
application subdirs, like <tt>akregator/</tt>, <tt>amarok/</tt>,
<tt>arts/</tt>, <tt>k3b/</tt>, etc. You will also find a <tt>KDE/</tt>
subdir, containing the official KDE releases since time immemorial.

One special subdir is found in <tt>/branches</tt>: <tt>work/</tt>. This
subdir contains the so-called "work branches", that is, branches containing
features being worked on, sometimes highly experimental. Multi-application
work branches always are checked in to <tt>/branches/work/</tt>, but
single-application branches may be found in each application's subdir. That
is a decision left to the developers.

== Checking out and updating ==

=== Checking out ===
In order to check out something with Subversion, you use the <tt>checkout</tt> subcommand.

'''WARNING:''' If you checkout trunk/KDE/ or branches/KDE/foo/ you will download complete kde-i18n!

Suppose you wanted to check out only KDevelop from the KDE repository. You would do:

CVS command:
cvs -d :pserver:yourname@cvs.kde.org:/home/kde login
cvs -d :pserver:yourname@cvs.kde.org:/home/kde checkout kdevelop

Subversion command:

CVS users currently using ssh access, should use protocol svn+ssh,
CVS users currently using password access, should use protocol https
in the following.

svn checkout <protocol>://<username>@svn.kde.org/home/kde/trunk/KDE/kdevelop

=== Updating ===

In order to update, you use the <tt>update</tt> subcommand.

This is no different from CVS: you change into your checked out copy (for those new to this whole process, the checked out copy should be in your Home folder) and issue a <tt>svn update</tt> (or, shorter, <tt>svn up</tt>) command.

== Knowing the status of a file ==

To know which local files you had modified, in CVS most people did
cvs up
and looked at the files with '''M''', this does not work with svn so you have to do
svn status
to know the status of the files.

== Committing to the repository ==

Just like in CVS, committing to the Subversion repository is accomplished
with the <tt>commit</tt> or <tt>checkin</tt> (<tt>ci</tt> for short) subcommands.

CVS command:
cvs commit
# or
cvs ci
# or
cvs ci filename.cpp

Subversion command:
svn commit
# or
svn ci
# or
svn ci filename.cpp

This way, <tt>svn</tt> will launch the editor specified in <tt>$SVN_EDITOR</tt> for you
to compose the commit message. If you prefer, you can give <tt>svn</tt> the -m
oprtion with your full message:

svn ci -m "Updating protocol to conform to HTTP/1.1"

== Ignoring files ==

Subversion stores ignored files per directory. To edit the ignored
files of the directory you are currently in, do
svn propedit svn:ignore .
that will launch your editor, write there the names of the files you want to
ignore, one file per line. Once you are done, do a commit so the ignored list
file gets updated on the server.

A lot of files were ignored in CVS with help from global ignore list which
is not supported yet by SVN. You can wait for svn 1.3 or you need to add the
ignore list to the [miscellany] group in your {{path|~/.subversion/config}} (all in
one line):

global-ignores = *.o *.lo *.la .*.rej *.rej .*~ *~ .#* #*# .DS_Store *.moc
*.moc.cc *.moc.cpp config.log config.status config.cache *.gmo .deps .libs
SunWS_cache *.lo *.la *.rpo *.la.closure *_la_closure.cpp *_la_closure.cc
*_la_closure.cxx *.all_cc.cc *.all_cpp.cpp *.all_C.C *.all_cxx.cxx
*_meta_unload.cc *_meta_unload.h *_meta_unload.cpp *_meta_unload.C
*_meta_unload.cxx index.cache.bz2 .memdump Makefile.rules.in Makefile.calls.in
Makefile.rules Makefile.calls autom4te.cache *.kidl

== Working with multiple revisions and branches ==

Unlike CVS, Subversion doesn't generate a revision number for each file
modified. Instead, the full repository is versioned, as a whole. This way, a
given revision number represents the state the repository was on a given date.
In other words, a revision number is like a timestamp (in fact, the Subversion
server uses this fact to search for dates in the repository faster).

So, for instance, when you check out the KDE repository, Subversion will
tell you the following:

Updated to revision 403821.

This means that the latest revision available at the time of the operation
was 403821. If you make a modification and commit, Subversion will update the
server-side revision and will inform you of it. Like CVS, only the committed
files will be updated: you will need run <tt>cvs up</tt> to update the rest of the
files.

If you want to retrieve a specific revision of a file, you can use the <tt>-r</tt>
switch. Besides the revision number itself, -r accepts a number of other
possibilities:

* The revision number: for example, use -r 403819 to retrieve that version
* '''BASE''': the revision you updated to
* '''COMMITTED''': the revision a file was last modified, before BASE
* '''PREV''': the revision of the previous commit to the file before COMMITTED
* '''HEAD''': the most recent revision available in the server
* '''{ date }''': between curly brackets, you can specify a date for searching the closest revisions

The following illustrates the evolution of the keywords:

# You run <tt>svn up</tt> to update to the latest available revision. Suppose Subversion tells you it updated to revision 403821. This means that HEAD and BASE are 403821.
# You modify file README and commit it. Suppose Subversion tells you it committed revision 403822. This means HEAD, BASE and COMMITTED are 403822.
# You modify the file again and commit it. Now PREV is 403822, but HEAD, BASE and COMMITTED are updated to a new value (suppose it's 403823).
# Now someone else modifies the repository, and you update your working copy. If Subversion tells you it updated to 403824, this means now HEAD and BASE are moved to 403824 (but PREV and COMMITTED stay the same)
# If someone modifies the README file now, HEAD is moved. The other keywords stay the same for you, until you update. At this time, we will have HEAD = 403825 (the latest available revision), BASE = 403824 (the revision you last updated to), COMMITTED = 403823 (the revision of the latest change to the file when you last updated) and PREV = 403822 (the revision of the change before COMMITTED)

Those keywords are useful to retrieve logs and diffs for commits to the
repository.

If you want to see the difference between your working copy and BASE, you
can run:

svn diff

This is a very fast operation, since Subversion keeps a local copy of BASE.
It doesn't need a network connection to accomplish this operation.

If you want to see the difference between your local copy and the latest
available on the server, you will run:

svn diff -r HEAD

If you want to see what has changed in the repository since you've last updated, you can use:
svn diff -r BASE:HEAD

If you want to see the last change to a file before BASE, you can use:
svn diff -r PREV:BASE
# or
svn diff -r PREV:COMMITTED

That is also valid for the <tt>svn log</tt> command.

== Linking in subdirectories from other places ==

It can happen you would like to include a copy of a subdirectory from another place, but just for convenience, not for developing the code in there. Of course it should be updated automatically whenever the original changes. Subversion can help you. You need to edit the property <tt>svn:external</tt> of the directory the subdirectory should be added to. So for the current directory you use
svn propedit svn:externals .
and then enter lines of the form
libkhalkhi svn://anonsvn.kde.org/home/kde/trunk/playground/pim/khalkhi
Updating will now fetch <tt>/trunk/playground/pim/khalkhi</tt> into the subdirectoy <tt>libkhalkhi</tt>.

{{warning|Beware that you cannot commit changes you did to the local copy of the external subdirectory, it is just a readonly copy.}}

You use <tt>svn://anonsvn.kde.org</tt> and not another protocol, because <tt>anonsvn.kde.org</tt> is accessible to everyone. Using <tt>https:</tt> or <tt>svn+ssh:</tt> would only work for users of that protocol. There are still some small disadvantage with <tt>anonsvn.kde.org</tt>: It is not always in synchronization with <tt>svn.kde.org</tt>, so updates in the original branch may take a while to appear on <tt>anonsvn.kde.org</tt>. And some strict firewalls are blocking the <tt>svn:</tt> protocol.

A special case in KDE 3 is the subdirectory <tt>admin</tt>, containing the KDE 3 build utilities. It is linked in to the top directory in all modules, and maintained in <tt>/branches/KDE/3.5/kde-common</tt>. For <tt>admin</tt> the KDE subversion server is configured to allow readonly access for everyone, so if you see
admin https://svn.kde.org/home/kde/branches/KDE/3.5/kde-common/admin
there is no need to change this.

== More information on the kde wiki ==

See [http://wiki.kde.org/tiki-index.php?page=KDE%20Subversion%20HOWTO the KDE wiki] for more
information about subversion in KDE

Getting Started/Set up KDE 4 for development (de)

2008-01-14T17:04:09Z

DrSlowDecay: Changed to german templates

{{Template:I18n/Language Navigation Bar|Getting_Started/Set_up_KDE_4_for_development}}
{{TutorialBrowser (de)|

series=Am Anfang|

name=KDE 4 für Entwicklung von Software aufsetzen|

pre=[[Getting_Started/Build/KDE4 (de)|KDE 4 erzeugen]]|

next=[[Development (de)|Anderes zum Thema Entwickeln in KDE4]]|

}}

{{note (de)|Diese Seite setzt voraus, dass Sie bereits kdelibs, kdepimlibs und kdebase anhand der der Anleitung unter [[Getting Started/Build/KDE4]] erstellt haben}}

== KDE 4 Anwendungen & Sitzungen starten ==

Um mit der Entwicklung für KDE 4 zu beginnen, gibt es folgende drei Möglichkeiten:
* Sie können [[Getting_Started/Set_up_KDE_4_for_development_(de)#KDE_4_Anwendungen_starten|KDE 4 Anwendungen neben anderen Anwendungen]] in Ihrer aktuellen Desktop Umgebung ausführehn.
* Sie können in Ihre aktuelle Desktop Umgebung [[Getting_Started/Set_up_KDE_4_for_development_(de)#Eingebettete_KDE_4_Sitzung|eine KDE 4 Sitzung einbetten]].
* Sie können [[Getting_Started/Set_up_KDE_4_for_development_(de)#Eigenständige_KDE_4_Sitzung|KDE 4 als eigene Sitzung]] ausführen.

Alle drei Optionen werden nachfolgend beschrieben.

{{Note (de)|
Wenn Sie beim ausführen von KDE 4 Anwendungen Fehler wie den folgenden erhalten:
Qt: Session management error: Could not open network socket
QMutex::lock: Deadlock detected in thread -1241241936
Oder wenn Sie startkde ausführen und es hängenbleibt, lesen Sie [http://www.nabble.com/QMutex::lock:-Deadlock-detected---running-KDE4-apps-%22using-the-normal-shell%22-t3584446.html diesen Artikel] für einen möglichen Ausweg.
}}

=== KDE 4 Anwendungen starten ===
==== Auf der normalen Shell mit sux ====

Für diese Methode wird das Tool '''sux''' (http://fgouget.free.fr/sux/sux-readme.shtml) benötigt. '''sux''' ist in den meisten Distributionen bereits enthalten. Anderenfalls können Sie auf die unten beschriebene Methode ''Normale Shell ohne sux'' zurückgreifen. '''sux''' erlaubt Ihnen, zu einem anderen Nutzer zu wechseln und konfiguriert dabei automatisch das X Forwarding (Authentifizierung und Export der DISPLAY Variable).

Um sich anzumelden, geben Sie <code bash>sux - kde-devel</code> ein.

Alle Umgebungsvariablen und alles sonstige sollten korrekt von Ihrer {{path|[[Getting_Started/Increased_Productivity_in_KDE4_with_Scripts/.bashrc|.bashrc]]}}
gesetzt werden. Um eine Applikation zu starten, geben Sie einfach ihren Namen ein; zum Beispiel: <code bash>kwrite</code>
{{Note (de)|
Wenn Sie Fehlermeldungen über fehlende MIME-Typen oder ähnliches erhalten, versuchen Sie folgendes:
* führen Sie <code bash>unset XDG_DATA_DIRS ; kbuildsycoca4</code> aus.
}}

==== Normal Shell ohne sux ====
Die einfachste Methode um KDE 4 Anwendungen zu starten, ist es <tt>su</tt> zur Anmeldung als <tt>kde-devel</tt> Benutzer zu benutzen und dann einfach die gewünschten KDE 4 Anwendung von der Shell aufzurufen. Um sich anzumelden, geben Sie <code bash>su - kde-devel</code>
ein und nachdem Sie Ihr Passwort eingegeben haben führen Sie
<code bash>export DISPLAY=:0</code> aus.
{{Note (de)|Das Exportieren der <tt>DISPLAY</tt> Variable ist nötig, damit die KDE 4 Anwendungen auf Ihrem normalen KDE 3 Desktop erscheinen.}}
Alle Umgebungsvariablen und alles sonstige sollte bereits von Ihrer {{path|[[Getting_Started/Increased_Productivity_in_KDE4_with_Scripts/.bashrc|.bashrc]]}} korrekt gesetzt worden sein. Um eine Anwendung zu starten, geben sie einfach ihren namen ein; zum Beispiel: <code bash>kwrite</code>
{{Note (de)|
Wenn Sie Fehlermeldungen über fehlende MIME-Typen oder ähnliches erhalten, versuchen Sie folgendes:
* führen Sie <code bash>unset XDG_DATA_DIRS ; kbuildsycoca4</code> aus
}}
{{Note (de)|
Wenn Sie eine Fehlermeldung erhalten, dass Sie sich nicht mit einem X-Server verbinden können, versuchen Sie
<code bash>sudo xhost +local:kde-devel</code>
unter Ihrem normalen KDE 3 Account auszuführen um sicher zu gehen das die Anwendung sich mit der gerade laufenden X-Sitzung verbinden kann.

Obwohl Ihr X-Server ankommende TCP Verbindungen akzeptieren sollte, ist dies oft von Distributionsseite her deaktiviert (so etwa unter Kubuntu Feisty). Wenn Sie <tt>kdm</tt> benutzen, müssen Sie die Datei <tt>/etc/kde3/kdm/kdmrc</tt> als root bearbeiten und überprüfen, das sie nicht folgendes enthält:
<code>ServerArgsLocal=-nolisten tcp</code>
Wenn Sie dies geändert haben, müssen Sie den X-Server neu starten.
Der <tt>xhost</tt> Befehl sollte nun nicht mehr die Meldung "unable to open display" ausgeben.

Aus Bequemlichkeit sollte dies automatisch beim Anmelden ihres normalen Benutzers geschehen. Um dies zu erreichen, erstellen Sie eine neue Datei unter <tt>$HOME/.kde/Autostart</tt> Ihres normalen Benutzers mit dem folgenden Inhalt:
<code bash>
#! /bin/sh
xhost +local:kde-devel
</code>
Stellen Sie sicher, das die neue Datei ausführbar ist, indem Sie <tt>chmod +x</tt> für die Datei ausführen.

Wenn Sie mehr über die '''Sicherheitsrisiken''' in Bezug auf <tt>xhost</tt> erfahren möchten, lesen Sie [http://bau2.uibk.ac.at/matic/xsecur.htm diesen Artikel]
}}

==== Benutzung von SSH ====

Der einfachste Weg um eine KDE 4 Anwendung über SSH auf Ihrem aktuellen Desktop auszuführen, ist es auf folgendem Weg eine Shell mit X-Forwarding zu bekommen:
<code bash>ssh -X kde-devel@localhost</code>
Jetzt können Sie KDE Anwendungen wie gewöhnlich ausführen, zum Beispiel:
<code bash>kwrite</code>
Diese zwei Zeilen können auf einfache Weise kombiniert werden:
<code bash>ssh -X kde-devel@localhost kwrite</code>

{{Note (de)|
Falls Sie Fehlermeldungen erhalten, probieren Sie die Tips aus dem vorhergehenden Abschnitt aus.
}}

===== Anmeldung ohne Passwort =====
Bevor Sie vorherige Methode sinnvoll benutzen können, müssen Sie eine Anmeldung ohne Passwort einrichten. Dafür führen Sie folgenden Befehl unter Ihrem normalen Benutzeraccount aus:
<code bash>ssh-keygen -t rsa</code>
Drücken Sie drei mal RETURN um den Pfad {{path|~/.ssh/id_rsa}} zu akzeptieren und ein leeres Passwort zu vergeben. Anschliessen kopieren Sie die einzelne Zeile aus {{path|~/.ssh/id_rsa.pub}} die Ihnen die Ausgabe von
<code bash>cat ~/.ssh/id_rsa.pub</code> liefert, in die Zwischenablage.
Wechseln Sie nun mit <tt>ssh</tt> zurück zum <tt>kde-devel</tt> Benutzer öffnen Sie die Datei {{path|$HOME/.ssh/authorized_keys}} auf folgende Weise:
ssh -X kde-devel@localhost $HOME/kde/bin/kwrite \
$HOME/.ssh/authorized_keys
Fügen Sie dort die zuvor kopierte Zeile ein, speichern Sie die Datei und beenden Sie KWrite. Versuchen Sie nun nochmal KWrite mit dem gleichen SSH-Befehl auszuführen; Sie sollten nun kein Passwort mehr benötigen:
<code bash>ssh -X kde-devel@localhost $HOME/kde/bin/kwrite</code>

{{warning (de)|Das Anmelden per SSH ohne Passwort birgt gewisse '''Sicherheitsrisiken'''. Vergewissern Sie sich deshalb, dass Ihre <tt>~/.ssh/id_rsa</tt> Datei geschützt ist, indem Sie den Zugriff auf sie mit
<code bash>chmod og-xrw ~/.ssh/id_rsa</code> einschränken (Die Datei sollte diese Rechte eigentlich bereits bei der Erstellung erhalten haben)}}

===== Die SSH desktop Datei =====
Wenn Sie Anwendungen einfacher benutzen wollen, als Sie per SSH-Befehl von der Shell zu starten, besteht ein Weg darin, <tt>.desktop</tt> Dateien zu erstellen die automatisch per <tt>ssh</tt> zum anderen Benutzer wechseln.
{{Note (de)|Dies ist nur dann nützlich, wenn Ihre Desktop-Umgebung .desktop Dateien unterstützt. Immerhin KDE und GNOME tuen dies.}}

Sie können eine existierenden .desktop Datei als Vorlage verwenden (Etwa eine von Ihrem Desktop) oder eine neue erstellen. Die Idee dahinter ist, dem auszuführenden Kommando die SSH-Verbindung auf folgende Weise voranzustellen:
<code bash>
ssh -X kde-devel@localhost $HOME/kde/bin/
</code>

Eine einfache .desktop Datei die KWrite ausführt würde folgenden Inhalt haben:

<code ini>
[Desktop Entry]
Categories=Qt;KDE;TextEditor;
Comment=
DocPath=kwrite/index.html
Encoding=UTF-8
Exec=ssh -X kde-devel@localhost /home/kde-devel/kde/bin/kwrite %U
GenericName=Text Editor
Icon=kwrite
InitialPreference=8
MimeType=text/plain
Name=KWrite (kde-devel)
Path=
StartupNotify=false
Terminal=false
TerminalOptions=
Type=Application
X-DBUS-StartupType=Multi
X-DCOP-ServiceType=non
X-KDE-StartupNotify=true
X-KDE-SubstituteUID=false
X-KDE-Username=
</code>

{{tip|Anwendung, die wie hier über SSH gestartet werden, lösen nicht die korrekten Startereignisse aus, so dass Sie besser die "Startrückmeldung" für Ihre .desktop Dateien deaktivieren sollten.}}

{{note (de)|Um auf diese Weise eine .desktop-Datei für KDE 4 Anwendungen zu erstellen, muss das Paket der Anwendung mit <tt>cmakekde</tt> in <tt>~/kde/bin</tt> installiert worden sein.}}

=== Starten von KDE 4 Sitzungen ===
==== Eingebettete KDE 4 Sitzung ====
{|align="right"
|[[image:Snapshot1.png|right|thumb|200px|Nested]]
|}
Anstatt für die Software-Entwicklung einen vollständigen virtuellen X-Server zu benutzen, können Sie Xephyr zur Einbettung Ihrer KDE 4 Sitzung in Ihr KDE 3 oder eine andere X11-Umgebung verwenden.

Sie können dies auch mit xnest erreichen aber da xnest nicht mit Erweiterungen wie Render umgehen kann, bevorzugen viele Leute Xephyr.

Wenn Sie eine minimale KDE Sitzung verwenden wollen, führen Sie einfach Xephyr aus: (in Kubuntu als xserver-xephyr verfügbar; Gentoo Benutzer kompilieren x11-base/xorg-server mit USE="kdrive"):

Xephyr :1&

Sie können KDE nun ausführen:

export DISPLAY=:1
/path/to/kde4/bin/startkde-modified &

startkde-modified ist eine Kopie des startkde-Skripts welches die folgenden Zeilen am Anfang enthält:

<code bash>
export KDEDIR=`kde4-config --prefix`
export LD_LIBRARY_PATH=$KDEDIR/lib
export PATH=$KDEDIR/bin/:$PATH
export KDEHOME=~/.kde4
</code>

Sie können Xephyr auch mit KDM über das Xdmcp Protokoll benutzen und einfach eine neue KDE 4 Sitzung zu KDM hinzufügen.

Unter Kubuntu können Sie das erreichen indem Sie

<code ini>
[Xdmcp]
# Whether KDM should listen to incoming XDMCP requests.
# Default is true
Enable=false
</code>

in {{path|/etc/kde3/kdm/kdmrc}} zu

<code ini>
[Xdmcp]
# Whether KDM should listen to incoming XDMCP requests.
# Default is true
Enable=true
</code>

verändern und Ihre {{path|/etc/kde3/kdm/Xaccess}} anpassen um ihrem lokalen System Zugriff zu gewähren. Zusätzlich sollten Sie eine Blockierende Regel für alle Ihre externen Schnittstellen für den Xdmcp Port einrichten falls Sie dies auf einem Laptop oder einem PC in einer unsicheren Umgebung verwenden.

Wenn Sie soweit sind, führen Sie einfach Xephyr aus:

Xephyr -query localhost :1 -host-cursor -screen 1024x768&

wobei <tt>-host-cursor</tt> versucht den Cursor des Hosts zu benutzen und <tt>-screen</tt> die Auflösung des Bildschirms festlegt.

Hinweis: Wenn Sie viele Fehlermeldungen bezüglich abgewiesener Verbindungen erhalten, sollten Sie die Option -ac an Xephyr übergeben:

Xephyr -ac :1&

Eine andere Möglichkeit die Sie versuchen können, wenn Sie diese Meldungen erhalten, ist es dem kde-devel Benutzer Zugriff auf den X-Server zu geben. Als root oder mit sudo führen Sie dazu folgenden Befehl aus:

xhost +local:kde-devel

Falls Ihnen Xephyr nicht zur Verfügung steht, können Sie auch Xnest benutzen:

Xnest -ac :1& export DISPLAY=:1

 
-----
{{improve}}
[[User:Sping|Sping]] 00:25, 9 April 2007 (CEST) 
I use this for my start script ''nested_kde4.sh'':

#! /bin/bash
NESTED_KDE_DISPLAY_BACKUP=$DISPLAY
export DISPLAY=:0
Xephyr :1 -screen 1024x768 &
export DISPLAY=:1
$HOME/kde/bin/startkde-modified &
export DISPLAY=${NESTED_KDE_DISPLAY_BACKUP}

Falls Sie folgende Fehlermeldung erhalten:

"Call to lnusertemp failed (temporary directories full?).
Check your installation."

versuchen Sie folgendes:

mkdir /var/tmp/kde-devel-kde4

Der obige Code setzt voraus das sie als Benutzer ''kde-devel'' arbeiten.
{{Note (de)|In den meisten Fällen müssen Sie ''startkde-modified'' mit ''startkde'' ersetzen}}
-----

==== Eigenständige KDE 4 Sitzung ====
{|align="right"
|[[image:solitary.png|right|thumb|200px|Solitary]]
|}
Um eine eigenständige KDE 4 Sitzung auszuführen, können Sie sie entweder, wie gewöhnlich, auf folgende Weise von der Kommandozeile starten:

X :1 & export DISPLAY=:1
startkde

{{Note|Wenn der X-Server die Verbindung verweigert und dabei folgendes ausgibt: <tt>Xlib: connection to ":1.0" refused by server</tt>, versuchen Sie <tt>X -ac :1</tt> stattdessen.}}

oder Sie können KDE 4 zu Ihrem Login Manager hinzufügen. Wenn Sie KDM (oder einen kompatiblen Login Manager) benutzen, wird dies durch Erstellen einer .desktop Datei in entweder {{path|`kde-config --prefix`/share/apps/kdm/sessions/}} oder in {{path|/usr/share/xsessions/}} erreicht. Der einfachste Weg führt dabei über das kopieren einer existierenden {{path|kde.desktop}}-Datei nach {{path|kde4.desktop}}. Öffnen Sie diese neue .desktop-Datei in einem Texteditor und ändern Sie die Einträge zu <tt>Exec</tt>, <tt>TryExec</tt> und <tt>Name</tt> auf folgende Weise:

<code ini>
Exec=$HOME/kde/bin/startkde
TryExec=$HOME/kde/bin/startkde
Name=KDE4
</code>

Ersetzen Sie {{path|$HOME/kde}} in obigem Beispiel mit dem Pfad unter dem Sie KDE 4 installiert haben.

Nach dem Neustart des Login Managers (<tt>Alt+e</tt> in KDM) sollte dieser neue Eintrag im Sitzungs-Menu erscheinen.

{{Note|Sie sollten den Pfad zum 'qdbus' Programm (normalerweise ist dies $QTDIR/bin) in Ihrer $PATH Variable haben um sich erfolgreich anzumelden. Falls es dort nicht ist, werden Sie eine Fehlermeldung "Could not start DBus. Check your installation." erhalten.}}

== Entwicklungs Aufgaben ==
=== KDevelop ===

Dieser Abschnitt wird Ihnen erklären, wie sie KDevelop 3.4 benutzen um KDE 4 Anwendungen zu entwickeln. Wenn sie Fragen, Korrekturen oder Bedenken zu diesem Abschnitt haben, notieren Sie diese bitte auf der Diskussions-Seite.

==== Voraussetzungen ====

Sie benötigen hierfür mindestens KDevelop 3.4, das immernoch eine KDE 3 Anwendung ist. Versionen vor 3.4 haben unter anderem keine Qt 4 Unterstützung. Die KDE 4 Version von KDevelop ist für den produktiven Einsatz noch nicht geeignet. Sie erhalten KDevelop auf der [http://www.kdevelop.org/index.html?filename=3.4/download.html KDevelop Homepage]. Installieren Sie KDevelop wie alle anderen KDE 3 Anwendungen unter Ihrem normalen Benutzer und '''nicht''' mit Ihrem ''kde-devel'' Benutzer.

Sie benötigen ausserdem die neueste ''GDB'' Version. Die aktuelle ist 6.6.0.

Weiterhin müssen Sie die kdelibs API Dokumentation lokal vorliegend haben, was unter [[Getting_Started/Build/KDE4_(de)#Generating_local_API_documentation|Anleitung zum Erstellen]] beschrieben wird.

Ausserdem benötigen Sie noch ''ctags'', ''htdig'', ''htmerge'' und ''htsearch''. ''valgrind'' und ''callgrind'' könnten auch nützlich sein.

Stellen Sie sicher, das sie den Schritten unter KDE 4 [[Getting_Started/Build/KDE4 (de)|Anleitung zum Erstellen]] befolgt und eine funktionierende KDE 4 Umgebung erstellt haben. Prüfen Sie, ob sich einfache KDE 4 Anwendungen wie ''Konsole'' oder ''KWrite'' von der Kommandozeile des kde-devel Benutzers ohne Probleme starten lassen.

Die folgenden Schritte werden alle mit dem '''kde-devel''' Benutzer ausgeführt. Sie müssen sich mit <code bash>su - kde-devel</code> unter diesem Benutzer anmelden.

==== Die Umgebung aufsetzen ====

KDevelop hat keine native Unterstützung für CMake Projekte. Glücklicherweise hat CMake die Fähigkeit selbst KDevelop Projekt Dateien zu erstellen. Um dies zu erreichen, müssen Sie CMake den Parameter ''-GKDevelop3'' übergeben. Dies bewegt CMake dazu, Projektdateien für KDevelop neben den normalen Makefiles zu erstellen. Der beste Weg dazu ist es, die '''cmakekde ''' Funktion in Ihrer [[Getting_Started/Increased_Productivity_in_KDE4_with_Scripts/.bashrc|{{path|.bashrc}}]] anzupassen. Ändern Sie einfach
<code bash>
cmake $srcFolder -DCMAKE_INSTALL_PREFIX=$KDEDIR \
-DCMAKE_BUILD_TYPE=debugfull&& \
make && \
make install;
</code>
in
<code bash>
cmake $srcFolder -GKDevelop3 -DCMAKE_INSTALL_PREFIX=$KDEDIR \
-DCMAKE_BUILD_TYPE=debugfull&& \
make && \
make install;
</code>

Nachdem Sie das getan haben, melden Sie sich erneut an, damit sich die Veränderungen an der {{path|.bashrc}} Datei auswirken. Dann müssen Sie ''cmakekde'' erneut im (Wurzel) build Verzeichnis des Projekts an dem Sie mit KDevelop arbeiten wollen (wenn sie vorher nicht ''-GKDevelop3'' im [[Getting_Started/Build/KDE4_(de)#Setting_up_the_environment|Erstellungsschritt]] ausgeführt haben). Wenn Sie zum Beispiel an Konsole, welches in ''kdebase'' liegt, arbeiten möchten, müssen Sie cmakekde im {{path|$KDE_BUILD/KDE/kdebase}} Verzeichnis ausführen. Dies erstellt unglücklicherweise alles erneut, aber nur einmal wenn Sie den Generator ändern.

Da alle Umgebungsvariablen des kde-devel Benutzers KDE 4 spezifisch sind, müssen diese zurückgesetzt werden, um der KDE 3 Umgebung zu entsprechen bevor KDevelop gestartet wird. Am einfachsten wird dies erreicht, indem Sie folgende Funktion zu Ihrer {{path|.bashrc}} hinzufügen:

<code bash>
function start3app {
mkdir -p /tmp/$USER-kde
export PATH=/opt/kde3/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11:/usr/games
export LD_LIBRARY_PATH=
export KDETMP=/tmp/$USER-kde
export KDEVARTMP=/var/tmp/$USER-kde
export KDEHOME=$HOME/.kde
export KDEDIR=/usr
export KDEDIRS=$KDEDIR
export DISPLAY=:0
eval "$@"
source $HOME/.bashrc #Reset environment variables again
}
</code>

Die ''PATH'' und ''LD_LIBRARY_PATH'' Variable werden vom KDE 3 Benutzer übernommen, und sie könnten auf Ihrem System abweichen, Geben Sie <code bash>echo $PATH</code> und <code bash>echo $LD_LIBRARY_PATH</code> als normaler KDE 3 Benutzer ein, um diese Werte zu erhalten. Die obigen Funktion nimmt an, das KDE 3 im {{path|/usr}} Verzeichnis installiert ist, wie es unter Debian-Systemen der Fall ist. Falls Ihr KDE 3 in einem anderen Verzeichnis installiert ist, müssen Sie die Zeile die ''KDEDIR'' setzt entsprechend anpassen. Hier ist ein Beispiel, wie sie herausfinden unter welchem Verzeichnis KDE installiert ist; in diesem Beispiel ist es /opt/kde3:

<code bash>
kde-config --prefix
/opt/kde3
</code>

Jetzt sollten Sie KDevelop starten können, indem Sie <tt>start3app kdevelop</tt> eingeben. Machen sie dies jetzt.

{{tip|
Sie können jede KDE 3 Anwendung mit der <tt>start3app</tt> Funktion starten. Nützlich ist das zum Beispiele für ''Kompare'' und ''kdesvn''.

Sie können jedoch auf diesem Weg nicht ''KDbg'' starten umd KDE 4 Anwendungen zu debuggen, da sonst die die Umgebungsvariablen für die debuggte Anwendung falsch sind.
}}


===== TroubleShooting =====

'''Symptom:''' kdevelop meldet "cannot talk to klauncher". Sie können keine Datei öffnen.

'''Lösung:''' fügen Sie Ihren KDE Bibliotheks-Pfad zum LD_LIBRARY_PATH hinzu, e.g.:
export LD_LIBRARY_PATH=/opt/kde3/lib

==== Einrichten von KDevelop ====

Jetzt, da KDevelop gestartet ist, müssen Sie einige Einstellung vornehmen.
Gehen Sie dafür nach ''Einstellungen->KDevelop einrichten...->Dokumentation''. Entfernen Sie alle Einträge die für KDE 4 nicht relevant sind.

{{note (de)| Obwohl Umgebungsvariablen wie $HOME in diesem Abschnitt verwendet werden, sollten Sie diese mit echten Pfaden ersetzen, da KDevelop keine Umgebungsvariablen auflöst.}

Optional können Sie die kdelibs API Dokumentation hinzufügen. Sie müssen sie [[Getting_Started/Build/KDE4_(de)#Generating_local_API_documentation|zuvor erstellen]]. Dann fügen sie die Dokumentation durch Klick auf ''Hinzufügen...'' hinzu. In diesem Dialog verwenden Sie folgende Einstellungen:
* ''Typ'': Doxygen Documentation Collection (muss zuerst eingestellt werden)
* ''Ort'': {{path|$KDE_SRC/KDE/kdelibs/kdelibs-apidocs/index.html}}

Fügen Sie nun die Qt API Dokumentation hinzu, indem Sie folgende Einstellungen verwenden:
* ''Typ'': Qt Documentation Collection (muss zuerst eingestellt werden)
* ''Ort'': {{path|$HOME/qt-copy/doc/html/qt.dcf}}

Nachdem Sie die Dokumentation für kdelibs und die Qt API hinzugefügt haben, stellen sie sicher das alle Checkboxen (''TOC'',''Index'' und ''Suche'') aktiviert sind. Dann gehen Sie auf den Tab ''Volltextsuche'' und stellen sicherm das die Pfade zu den Programmen ''htdig'', ''htmerge'' und ''htsearch'' korrekt sind. Sie können den Einstellungs-Dialog nun schliessen.

Jetzt ist es an der Zeit das Projekt an dem Sie arbeiten möchten zu öffen indem sie auf ''Projekt->Projekt öffnen'' klicken. Die Projektdateien befinden sich im build-Verzeichnis. Für Konsole müssen Sie zum Beispiel die Datei {{path|$KDE_BUILD/KDE/kdebase/apps/konsole/konsole.kdevelop}} öffnen. Sie müssen nun einige Projektspezifische Einstellungen unter ''Projekt->Projekt Optionen'' vornehmen. Sie müssen das für jedes Projekt machen, an dem Sie arbeiten möchten.

{{note (de)|
Manchmal ist keine KDevelop Projektdatei für das Verzeichnis in dem Sie arbeiten möchten verfügbar.

Dies kann verschieden Gründe haben, es hängt davon ab wie die CMake-Dateien geschrieben wurden. Für gewöhnlich sollten CMake-Dateien, die eine <tt>project(projectname)</tt> Anweisung enthalten gut funktionieren. Wenn Sie mit CMake vertraut genug sind, können Sie versuchen, diese Anweisung hinzuzufügen.

Ein Workaround dafür ist es, einfach die KDevelop Projektdatei eines darüberliegenden Ordners zu verwenden. In diesem Fall müssen Sie den <tt>Make Active Directory</tt> Eintrag im Kontextmenu des <tt>File Selectors</tt> in der Sidebar benutzen. Damit können Sie die anderen, unerwünschten Verzeichnisse beim erstellen und installieren ignorieren.
}}

* ''C++ Unterstützung->Codevervollständigung''
:Hier müssen Sie die Vervollständigungs-Datenbanken für Qt und kdelibs hinzufügen und natürlich noch mehr wenn Sie mögen. Zum Beispiel könnten Sie eine Datenbank für ''kdepimlibs'' benötigen wenn sie an ''kdepim'' arbeiten.

:Für kdelibs klicken Sie den ''Hinzufügen...'' Button und wählen ''KDevelop Custom Directory PCS Importer'', dann fügen Sie Ihr KDE include Verzeichnis ({{path|$HOME/kde/include}}) zur Liste hinzu und fahren fort. Sie können den Dateiauswahldialog und den ''Hinzufügen...'' Button benutzen um es hinzuzufügen.

:Jetzt fügen Sie die Datenbank für Qt 4 hinzu indem Sie ''KDevelop Qt4 PCS Importer'' auswählen. Sie müssen das Qt 4 include-Verzeichnis welches Sie unter {{path|$HOME/qt-copy/include}} finden hinzufügen.

{{note (de)|Der Qt4 PCS Importer wird nur benötigt wenn Qt4 nicht installiert wurde, sie es also zum Beispiel direkt aus dem build-Verzeichnis heraus nutzen. Der Nachteil ber der Benutzung des Qt4 Importers ist das er während des Imports keinen Fortschritt anzeigt und die Applikation zu hängen scheint. Die Alternative ist es den Custom Directory PCS Importer dafür zu benutzen}}

* ''C++ Unterstützung->Qt Optionen''
:Aktivieren Sie ''Qt Options aktivieren'' und wählen Sie Qt4 als Ihre Version. Setzen Sie den ''QMake Binary'' Pfad auf {{path|$HOME/qt-copy/bin/qmake}}. Dann wählen Sie ''Qt 4 style'' als ''Qt include syntax''. Benutzen Sie {{path|$HOME/qt-copy/bin/designer}} für ''Designer Binary''. Benutzen Sie den ''Pluginpfade ändern'' Dialog um das Plugin-Verzeichnis von KDE hinzufügen und so die KDE widgets im Designer zu sehen. Um das zu erreichen fügen Sie {{path|$HOME/kde/lib/kde4/plugins}} in das Textfeld ein und klicken den ''Hinzufügen''-Button.

* ''Ausführungs Optionen''
:Stellen Sie sicher das für ''Executable'' der korrekte Wert eingestellt ist. Wenn Sie zum Beispiel Konsole ausführen wollen, geben Sie {{path|$KDE_BUILD/KDE/kdebase/apps/konsole/src/konsole}} an. Sie sollten ''--nofork'' zu den ''Debug Parametern'' hinzufügen oder das Debuggen von einigen Anwendungen wie ''KMail'' wird fehlschlagen.

:Da die ''start3app'' Funktion einige Umgebungsvariablen anpasst, müssen Sie diese hier zurücksetzen damit KDE 4 Anwendungen problemlos aus KDevelop heraus ausgeführt werden können.
:Für einige Anwendungen, wie Konsole, ist dies nicht unbedingt nötig aber andere wie KMail werden abstürzen wenn Sie die Variablen nicht anpassen.
:Klicken Sie einfach auf den ''Hinzufügen / Kopieren'' Button um neue Umgebungsvariablen hinzuzufügen. Sie werden die folgenden brauchen, die die selben wie in Ihrer [[Getting_Started/Increased_Productivity_in_KDE4_with_Scripts/.bashrc|{{path|.bashrc}}]] sind:

:{| border="1"
|-
! Name
! Value
|-
| KDEHOME
| $HOME/.kde4
|-
| PATH
| $KDEDIR/bin:$QTDIR/bin:/usr/local/bin:$PATH
|-
| LD_LIBRARY_PATH
| $KDEDIR/lib:$QTDIR/lib:$LD_LIBRARY_PATH
|-
| KDETMP
| /tmp/$USER-kde4
|-
| KDEVARTMP
| /var/tmp/$USER-kde4
|-
| KDEDIR
| $HOME/kde
|-
| KDEDIRS
| $KDEDIR
|-
| LD_BIND_NOW
| 42
|}

* ''Erstellungs Optionen->Erstellung''
:Stellen Sie sicher das hier das korrekte build-Verzeichnis eingetragen ist. Für Konsole ist es wiederum dieses: {{path|$KDE_BUILD/KDE/kdebase/apps/konsole}}.

* ''Erstellungs Optionen->Make''
:Sie sollten ''Abruch bei erstem Fehler'' aktivieren. Ausserdem sollten Sie ''VERBOSE='' oder ''VERBOSE=1'' zu ''Weitere Make Optionen'' hinzufügen um Aussagekraft des Erstellungsprozesses zu steuern.

:Wenn Sie mehr als einen Prozessor haben oder Sie Zugriff auf einen icecream cluster besitzen, sollten Sie die Option ''Mehrere Jobs ausführen'' aktivieren u nd die ''Anzahl der gleichzeitigen Prozesse'' auf die Anzahl der verfügbaren Prozessoren einstellen. Dies erhöht die Kompilierungsgeschwindigkeit. Es ist dsa gleiche wie die <tt>-j</tt> Option für ''Make''.

* ''Formatierung''
:Sie sollten alle Optionen hier so setzen, das sie zu dem Coding-Stil des Projekts an dem Sie arbeiten passen.

* ''CTags->Allgemein''
:Sie müssen den ''Pfad zur CTag Binary'' korrekt setzen, die sich in Debian unter {{path|/usr/bin/ctags}} befindet.

:Am besten aktivieren Sie noch die Option <tt>Bei mehr als einem Treffer, direkt zum Ersten gehen</tt>.

Jetzt sind Sie damit fertig Ihre Projekt-spezifischen Einstellungen zu konfigurieren. Sie sollten nun unter ''Einstellungen->Plugins konfigurieren...'' einige Plugins entfernen, die Sie nicht benötigen. Ich deaktiviere beispielsweise folgende Plugins:

Abbreviation Expansion, Code Snippets, Doxygen Support, Embedded Konsole, File Tree, '''Final Packaging Support''', "Open with" Menu Addon, QuickOpen, Regular Expression Tester, Scripting, '''Security Checker''', Shell Filtering and Insertion, Text Structure and Tools Menu Addition.

Sie sollten zumindest die Fettgedruckten entfernen.

Jetzt öffnen Sie, falls noch nicht geschehen, irgendeine Quelldatei. Dies aktiviert den Menueintrag ''Einstellungen->Editor konfigurieren...'', wo Sie die Tabulatoroptionen so einstellen müssen wie Sie im Projekt an dem Sie arbeiten benutzt werden. Die wichtigsten Einstellungen sind:
* ''Erscheinungsbild->Rahmen->Zeilennummern anzeigen'': Sollte aktiviert sein.
* ''Erscheinungsbild->Rahmen->Symbolränder anzeigen'': Sollte aktiviert sein.
* ''Bearbeiten->Tabulatoren''
* ''Bearbeiten->Statischer Zeilenumbruch->Markierung anzeigen'': Sollte aktiviert sein
* ''Einrückung->Automatische Einrückung->Einrückungs-Modus'': Sollte ''C Style'' sein
* ''Einrückung'' insgesamt

Im Hauptfenster klicken Sie auf den Tab ''CTags'' in der unteren Tableiset, dann klicken Sie auf ''Neu erstellen'' um eine CTags-Datenbank zur einfacheren Navigation im Quellcode zu erstellen.

Jetzt haben Sie alle wesentlichen Einstellunge vorgenommen, Gratulation!

==== KDevelop benutzen ====

Wenden Sie sich an das [http://docs.kde.org/development/en/kdevelop/kdevelop/ KDevelop Handbuch (englisch)] um generell Hilfe zu Ihrer Arbeit mit KDevelop zu erhalten. Der folgende Abschnitt wird nur Spezialfälle im Bezug auf KDE 4 enthalten.

===== Debugging =====

KDE Anwendungen haben viele Symbole, was bedeutet, dass sie viel Speicher benötigen um eine angemessene Ladezeit beim Debuggen zu erreichen. Um einen GDB Entwickler zu zitieren: "Ich würde mich weigern KDE auf etwas mit unter 1 GB RAM zu debuggen."
Wenn die Schrittfunktion des Debuggers zu langsam für Sie ist, versuchen Sie folgende Tips:
* Lokale Variablen verstecken. Der <tt>Lokal</tt> Teil im linken Variablen Tab verursacht einen erheblichen Geschwindigkeitsrückgang bei der Schrittweisen Ausführung wenn Sie viele lokale Variablen haben. Klappen sie einfach den <tt>Lokal</tt> Teil des Baums zu, die lokalen Variablen werden nun nicht bei jedem Schritt aktualisiert. Sie können immernoch die Variablen untersuchen indem sie die <tt>Ausdruck evaluieren</tt> Funktion benutzen.
* Benutzen Sie den Patch unter http://bugs.kde.org/show_bug.cgi?id=143977. Es verhindert die Aktualisierung des Framestack-Widgets bei jedem Schritt und beschleunigt damit die Schrittweise Ausführung erheblich. Der Patch führt zu einigen kleineren Ungereimtheiten weshalb er bisher noch nicht commited wurde.

{{Note (de)|
KDevelop unterstützt bisher keine Änderungen am CMake build System. Das bedeutet, das Sie KDevelop nicht dazu benutzen können, Dateien zum Projekt hinzuzufügen oder zu entfernen oder irgend einen anderen Aspekt des Buildprozesses Ihres Projekts zu modifizieren.

Sie müssen stattdessen die CMake Dateien per Hand anpassen und dann erneut <tt>cmakekde</tt> ausführen. Lesen Sie das [[Development/Tutorials/CMake (de)|CMake Tutorial]] um zu lernen wie man das macht.
}}

{{tip|Wenn Sie an Bibliotheken arbeiten, müssen Sie diese zuerst installieren bevor Sie Ihre Änderungen an diesen testen oder debuggen können.
Da this lästig und zeitverschlingend ist, sollten Sie für alle betreffenden Bibliotheken Symlinks erstellen ''(ln -s)'', die aus dem Build-Verzeichnis auf das Installations-Verzeichnis verweisen.

Oft benutzen selbst einfache Programme interne Bibliotheken, zum Beispiel ist der Einstellungsdialog von Konsole in Wirklichkeit eine Bibliothek,}}

[[Category:KDE4]]

Development/Tutorials/Localization/i18n Build Systems (de)

2007-12-26T17:34:29Z

DrSlowDecay: Some small translations

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n Build Systems}}

{{TutorialBrowser (de)|

series=Lokalization|

name=Das l10n Modul von KDE erzeugen|

pre=[[../i18n (de)|Beim Schreiben von Applikationen an die Lokalisation denken]]|
next=[[../Language Change (de)|Sprachänderungen behandeln]]|
}}

== Zusammenfassung ==
Da Ihre Applikationen in den vorigen Schritten vorbereitet wurde, lokalisiert zu werden, sehen wir uns jetzt an, wie man die notwendigen Schritte in das CMake Build-System Ihrer Applikation integriert.

First we'll explain the "theory" of the steps that need to happen from extracting message strings to installing the generated .po files. After that we'll look at how to implement those steps ([[#Theory: The xgettext toolchain]]). If your application is developed in KDE's subversion repository, many of those steps will happen automatically (see [[#handling i18n in KDE's subversion repository]]). Else you will want to read on in the [[#handling i18n in third party applications]] section.

== Theorie: Die xgettext toolchain ==

Making translations work consists of the following steps:
# Extract the translatable strings
# Merge the new or changed strings with existing translations
# Compile the translations into message catalogs
# Install the message catalogs
# Use the message catalogs in the application

=== Die Zeichenkette extrahieren ===

In this step, all the strings you marked as i18n()/ki18n()/etc. in your sources need to be collected into a translation template (.pot) file. Some translateable strings are also contained in .ui, .rc, or .kcfg files. Also tips-of-the-day need to be collected into the .pot file.

These steps are handled by {{path|xgettext}}, {{path|extractrc}}, and {{path|preparetips}} programs, respectively. In some cases you may also need {{path|extractattr}}.

=== Übersetzungen mischen ===

Generally, only a few translatable string will change at a time, in an application. Some will be removed, some will be added, some will be changed into different strings, and some will be moved around in the source files. These changes need to be reflected in the translations, but of course it would be a huge effort to redo the entire translation every time a string was changed. Rather the changes should be merged with the existing translations. This is the job of the {{path|msgmerge}} tool.

=== Übersetzungen kompilieren ===

In order to make message lookup fast, the .po files need to be compiled into so-called "message catalogs" (.mo / .gmo). This is done using the {{path|msgfmt}} tool.

=== Die Kataloge für Zeichenkette installieren ===

The compiled message catalogs need to be installed alongside the application. In KDE, the standard location for message catalogs is {{path|$KDEDIR/share/locale/xx/LC_MESSAGES/}}.

=== Die Kataloge für Zeichenketten benutzen ===

Finally, when the application is run, it needs to load the appropriate message catalog in order to be able to look up and show translated strings. In KDE applications, this is the job of the {{class|KLocale}} class, and in the great majority of cases happens automatically.

For some special cases, such as plugins, look at [[#Runtime Loading Of Catalogs]].

== i18n in KDE's subversion Repository behandeln ==

If your application is developed inside KDE's subversion repository, most of the steps outlined above are automated. In this case, generally, all you will need to do is provide a simple script called {{path|Messages.sh}}, which we will look at below.

In addition, if your top-level folder and .pot file have the same name, the svn2dist script will automatically include .po files when you use it to make a source tarball for your app.

Of course, for the curious, a more detailed account of what happens behind the scences is also provided.

=== Ein Messages.sh Skript schreiben ===

Basically, the only thing that is necessary to prepare and install translations for applications in KDE's subversion repository, is to provide information, which sources, ui-files or tips need to be translated. For this purpose, you write a small script called {{path|Messages.sh}} and place it in your sources. Here is an example with inline comments:

<code bash n>
#!bin/sh

# invoke the extractrc script on all .ui, .rc, and .kcfg files in the sources
# the results are stored in a pseudo .cpp file to be picked up by xgettext.
$EXTRACTRC `find . -name \*.rc -o -name \*.ui -o -name \*.kcfg` >> rc.cpp
# if your application contains tips-of-the-day, call preparetips as well.
$PREPARETIPS > tips.cpp
# call xgettext on all source files. If your sources have other filename
# extensions besides .cc, .cpp, and .h, just add them in the find call.
$XGETTEXT `find . -name \*.cc -o -name \*.cpp -o -name \*.h` -o $podir/APPNAME.pot
</code>

As you can see, this script contains only three actual lines of code, and not all may even be needed. The $XGETTEXT, $PREPARETIPS, $EXTRACTRC, and $podir environment variables are predefined, you do not need to worry about setting these. The only thing that you will need to do is to replace "APPNAME" with the name of your application (but see [[#Naming .pot Files]] for exceptions).

Try to make sure your Messages.sh script collects only those messages that are really needed. If in doubt, look at other Messages.sh files in the KDE subversion repository for inspiration, or - of course - ask.

=== Was geschieht hinter der Bühne ===

{{tip (de)|If your application is in the KDE code repository, all this happens automatically. If your code is not in the KDE repository, you must perform these steps yourself. See [[#handling i18n in third party applications]].}}

Periodically, the script {{path|extract-messages.sh}} (a.k.a. scripty) runs on the KDE server. This program basically calls all Messages.sh scripts in the repository with the appropriate parameters. The extracted messages are stored in template (.pot) files in the templates folder of the l10n module. See [[What Is Scripty]] for more information.

The KDE translation teams translate the messages and commit them into a messages folder corresponding to the language, which is further broken down by module. For example, German translated messages for konqueror are committed to {{path|l10n/de/messages/kdebase/konqueror.po}}.

When the l10n module is built, the .po files are compiled into a binary format for fast lookup and installed as .mo files to {{path|$KDEDIR/share/locale/xx/LC_MESSAGES/}}, where xx is the two-letter ISO 639 code for the language. These are called the message catalogs.

At runtime, the <tt>i18n(...)</tt> function, using the original string you coded, looks up the string in the message catalog of the user's desktop language and returns the translated string. If the message catalog is missing, or the specific string is not found, <tt>i18n(...)</tt> falls back to the original string in your code.

.desktop files in your project are handled separately. {{path|makemessages}} extracts strings, such as Name and Comment from the .desktop files and places them into a file named {{path|desktop_mmmm.pot}}, where mmmm is the module name, in the templates folder. Once translators have translated this file, makemessages inserts the translated strings back into the .desktop files. The list of strings extracted is in {{path|l10n/scripts/apply.cc}}. Here's the code that checks for them:

<code cppqt n>if (checkTag("Name", in, argc, argv, newFile))
continue;
if (checkTag("Comment", in, argc, argv, newFile))
continue;
if (checkTag("Language", in, argc, argv, newFile))
continue;
if (checkTag("Keywords", in, argc, argv, newFile))
continue;
if (checkTag("About", in, argc, argv, newFile))
continue;
if (checkTag("Description", in, argc, argv, newFile))
continue;
if (checkTag("GenericName", in, argc, argv, newFile))
continue;
if (checkTag("Query", in, argc, argv, newFile))
continue;
if (checkTag("ExtraNames", in, argc, argv, newFile))
continue;</code>

== i18n in Applikationen von dritten behandeln ==

If your application is developed outside of KDE's subversion repository, you need to take care of generating and installing message catalogs yourself. This is not too hard to do, but you should make sure you have a basic understanding of all steps involved, so you will probably want to read [[#Theory: The xgettext toolchain]], first.

Also, there is more than one way to deal with i18n in your application. We will outline one approach to do so for simple applications, but you may want to diverge from this, if you like to.

{{note (de)|The following improvements are needed in this section (or is this obsolete?):
How can messages for .desktop files be extracted?
How can translated .desktop messages be inserted back into .desktop files?}}

=== Allgemeine Überlegungen ===

The i18n generation process can roughly be divided into two steps:

# Extracting and merging messages
# Compiling and installing message catalogs

The first step really concerns the ''sources'', while the second step is a natural part of compiling and installing an application. Hence, while the second step should definitely be incorporated into the build system for your application (we assume CMake, here), there is no striking reason for the first step to be handled by the build system.

In fact, the extraction and merging of messages does not map well onto the CMake concept of out-of-source builds, and CMake can't provide too much help for this step, either.

Hence, in this tutorial, we will handle the first step with a standalone shell script, and only the second step will be handled by CMake.

=== Extrahieren und Mischen von Zeichenketten ===

If you have read the section [[#handling i18n in KDE's subversion repository]] you will know that in the KDE repository, message extraction and merging is handled by a simple script called Messages.sh, which is invoked by a script called {{path|extract-messages.sh}}. Outside of KDE's repository, you will need to take care of both parts, but fortunately, this is easy enough. Here's a sample script:

<code bash n>
#!/bin/sh
BASEDIR="../rkward/" # root of translatable sources
PROJECT="rkward" # project name
BUGADDR="http://sourceforge.net/tracker/?group_id=50231&atid=459007" # MSGID-Bugs
WDIR=`pwd` # working dir

echo "Preparing rc files"
cd ${BASEDIR}
# we use simple sorting to make sure the lines do not jump around too much from system to system
find . -name '*.rc' -o -name '*.ui' -o -name '*.kcfg' | sort > ${WDIR}/rcfiles.list
xargs --arg-file=${WDIR}/rcfiles.list extractrc > ${WDIR}/rc.cpp
# additional string for KAboutData
echo 'i18nc("NAME OF TRANSLATORS","Your names");' >> ${WDIR}/rc.cpp
echo 'i18nc("EMAIL OF TRANSLATORS","Your emails");' >> ${WDIR}/rc.cpp
cd ${WDIR}
echo "Done preparing rc files"

echo "Extracting messages"
cd ${BASEDIR}
# see above on sorting
find . -name '*.cpp' -o -name '*.h' -o -name '*.c' | sort > ${WDIR}/infiles.list
echo "rc.cpp" >> ${WDIR}/infiles.list
cd ${WDIR}
xgettext --from-code=UTF-8 -C -kde -ci18n -ki18n:1 -ki18nc:1c,2 -ki18np:1,2 -ki18ncp:1c,2,3 -ktr2i18n:1 \
-kI18N_NOOP:1 -kI18N_NOOP2:1c,2 -kaliasLocale -kki18n:1 -kki18nc:1c,2 -kki18np:1,2 -kki18ncp:1c,2,3 \
--msgid-bugs-address="${BUGADDR}" \
--files-from=infiles.list -D ${BASEDIR} -D ${WDIR} -o ${PROJECT}.pot || { echo "error while calling xgettext. aborting."; exit 1; }
echo "Done extracting messages"

echo "Merging translations"
catalogs=`find . -name '*.po'`
for cat in $catalogs; do
echo $cat
msgmerge -o $cat.new $cat ${PROJECT}.pot
mv $cat.new $cat
done
echo "Done merging translations"

echo "Cleaning up"
cd ${WDIR}
rm rcfiles.list
rm infiles.list
rm rc.cpp
echo "Done"
</code>

Of course you will want to adjust the variable definitions at the top, and - if needed - add code to extract tips-of-the-day or other additional strings.

The example script assumes that all .po files and the .pot file are kept in a single directory, which is appropriate for most projects.

=== Kompilieren und Installieren von Zeichenkettenkatalogen ===

Assuming you use the script from the previous section, you can place the following CMakeLists.txt in the directory containing the .po files:

<code>
FIND_PROGRAM(GETTEXT_MSGFMT_EXECUTABLE msgfmt)

IF(NOT GETTEXT_MSGFMT_EXECUTABLE)
MESSAGE(
"------
NOTE: msgfmt not found. Translations will *not* be installed
------")
ELSE(NOT GETTEXT_MSGFMT_EXECUTABLE)

SET(catalogname rkward)

ADD_CUSTOM_TARGET(translations ALL)

FILE(GLOB PO_FILES *.po)

FOREACH(_poFile ${PO_FILES})
GET_FILENAME_COMPONENT(_lang ${_poFile} NAME_WE)
SET(_gmoFile ${CMAKE_CURRENT_BINARY_DIR}/${_lang}.gmo)
ADD_CUSTOM_COMMAND(TARGET translations
COMMAND ${GETTEXT_MSGFMT_EXECUTABLE} --check -o ${_gmoFile} ${_poFile}
DEPENDS ${_poFile})
INSTALL(FILES ${_gmoFile} DESTINATION ${LOCALE_INSTALL_DIR}/${_lang}/LC_MESSAGES/ RENAME ${catalogname}.mo)
ENDFOREACH(_poFile ${PO_FILES})

ENDIF(NOT GETTEXT_MSGFMT_EXECUTABLE)
</code>

This iterates over all .po files in the directory, compiles them using msgfmt, and installs them to the standard location. You will want to change "catalogname" to the name of your application.

=== Übersetzungen erhalten ===

Now you just have to find translators to translate the extracted messages into the various languages. As your application gets used by more people, you will find that translators will volunteer to do this. Translated PO files then have to be stored in the po folder with the naming scheme <languagecode>.po.

== Sonderfälle (plugins, mehrere catalogs, etc.) ==

=== Kataloge zur Laufzeit laden ===

To have translations show up properly in an application, the name of the .pot file must match the name of the message catalog (.mo) file that your application will read at runtime. But what name will be used at runtime?

In general, it will be the value returned by <tt>{{class|KGlobal}}::instance()->instanceName()</tt>. But what will that be? The general rules for standalone applications are:
* the message catalog will default to the name of the application passed as the first argument to {{class|KAboutData}}
* if your code calls <tt>{{class|KLocale}}::setMainCatalog()</tt>, that name will be used instead
* if your code calls <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt>, the specified catalog will also be searched in addition to the main catalog

If your code does not call either of the {{class|KLocale}} methods mentioned above and your application is a plugin, it gets a little more complicated. If your code exports your plugin using the <tt>K_EXPORT_COMPONENT_FACTORY</tt> macro, like this:

<code cppqt>K_EXPORT_COMPONENT_FACTORY( libkhtmlkttsdplugin,
KGenericFactory<KHTMLPluginKTTSD>("khtmlkttsd") )</code>

then the catalog name will be the name passed in the {{class|KGenericFactory}} constructor - in the example above that woudl be <tt>khtmlkttsd</tt>. This is because the macro creates a {{class|Kinstance}} for you with the specified name.

However, some classes, such as <tt>KTextEditor</tt> create a <tt>KPart</tt> containing your component and the name passed in the macro is not used. In this case, you should call <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt> in the component's constructor.

If in doubt, the safest thing to do is to call <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt>.

{{tip|If you're not using the export macro for your plugin, you probably should be. See the API documentation of KGenericFactory for more information.}}

Calling <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt> if the catalog has already been inserted does nothing. However, calling <tt>{{class|KLocale}}::removeCatalog(const QString&)</tt> removes the catalog no matter how many times it has been inserted. Therefore, take care that you do not inadvertently remove the catalog when multiple components are sharing a single catalog. For example, the following sequence will break translations:

<code cppqt n>// Component A loads and uses catalog xyz by calling
insertCatalogue("xyz");
// Component B loads and also uses the same catalog.
insertCatalogue("xyz");
// component B unloads and calls
removeCatalogue("xyz")
// Component A now doesn't translate properly.</code>

Notice that a sequence such as above will occur automatically if both components A and B are loaded using the <tt>K_EXPORT_COMPONENT_FACTORY</tt> macro and pass the same name argument to the KGenericFactory constructor.

=== Benennung von .pot Dateien ===

The name that you settle on for both the .pot file and catalog should be governed by where your code resides. If it is a component of another application and resides in that application's source tree, you'll want to share the main catalog of the application.

If is a component of another application but resides elsewhere in the code repository, you will probably have to create a separate .pot, but keep in mind that .pot filenames must be unique across all of KDE.

If it is a component of another application, but resides in the source tree of a second application, you should share with the second application. For example, the KDE text-to-speach daemon (KTTSD) includes a plugin for embedded Kate in {{path|kdeaccessibility/kttsd}} source tree. Since the plugin is not installed unless kttsd is installed, it shares its catalog with kttsd and calls <tt>{{class|KLocale}}::insertCatalog("kttsd")</tt> to do this.

== Handbücher ==
Hanbücher, die im docbook Format geschrieben werden, werden von Applikationen anders behandelt. Die übersetzen Handbücher werden im l10n Modul in das doc Verzeichnis unter der jeweiligen Sprache geschrieben. Zusätzlich ist das doc Verzeichnis in Module und Applikationen unterteilt. So ist zum Beispiel das deutsche Kate Handbuch in {{path|l10n/de/docs/kdebase/kate}} geschrieben. Wenn es kompiliert wurde, wird es in {{path|$KDEDIR/share/doc/HTML/de/kate/index.cache.bz2}} installiert.

Bitte beachten Sie, dass es am jeweiligen Übersetzerteam liegt, die übersetzen Handbücher zu erzeugen, wann immer diese meinen, es wäre komplett.

[[Category:Programming]]

Development/Tutorials (de)

2007-12-21T16:45:12Z

DrSlowDecay: /* Lokalisation */ Added language change

{{Template:I18n/Language Navigation Bar|Development/Tutorials}}

{{improve (de)|Bitte hilf, die englische Seite vollständig ins Deutsche zu übersetzen.}}

== Einführung in die KDE 4 Programmierung ==
Sind Sie an der Entwicklung von Programmen für KDE 4 interesiert? Wenn ja sind Sie hier genau richtig. Diese Artikelserie richtet sich an alle, die noch nie mit KDE programmiert haben.
;[[Development/Tutorials/First program (de)|Hallo Welt!]]
:''Einführung in die Grundlagen der KDE Programmierung''

;[[Development/Tutorials/Using KXmlGuiWindow (de)|Erstellen eines Hauptfensters]]
:''Dieser Artikel erklärt, wie der wichtigste Teil eines grafischen Programmes erstellt wird: das Hauptfenster.''

;[[Development/Tutorials/Using KActions (de)|Die Verwendung von KActions]]
:''In diesem Artikel erfahren Sie, wie Aktionen und Werkzeugleisten (Toolbars) im Menü hinzugefügt werden können.''

== Grundlagen ==
;[[Development/Tutorials/KDE4 Porting Guide (de)|Ihre Applikation nach KDE 4 portieren]]
:''Anleitungen Qt3/KDE3 Applikationen nach Qt4/KDE4 zu portieren''

;[[Development/Tutorials/CMake (de)|Einführung in CMake]]
:''Wie man CMake in KDE 4 benutzt''

;[[Development/Tutorials/Common Programming Mistakes (de)|Häufige Programmierfehler]]
:''Einige häufige Fehler die man während der Entwicklung von Qt und KDE Applikationen machen kann und wie man sie vermeidet.''

;[[Development/Tutorials/Using Qt Designer (de)|Den Qt Designer benutzen um Benutzerschnittstellen zu erzeugen]]
:''Wie man UI Dateien mit dem Designer erzeugt und wie man diese in einem KDE Programm integriert.''

== Dienste: Applicationen and Plugins ==
;[[Development/Tutorials/Services/Introduction (de)|Einführung in das Dienst-Framework]]
:''Eine Einführung über das Dienst-Framework in KDE und was es dem Applikationsentwickler zur Verfügung stellen kann. Beschäftigt sich mit dem system configuration cache (SyCoCa), den benötigten Dateien und wie indizierte Informationen benutzt werden.

;[[Development/Tutorials/Services/Traders (de)|Dienste über Trader Queries finden]]
:''Wie man mit der Trader Query Syntax Dienste wie Plugins oder Mimetypes findet, die im SyCoCa zwischengespeichert wurden. ''

;[[Development/Tutorials/Services/Plugins (de)|Erstellen und Laden von Plugins mit KService]]
:''Zeigt, wie man eigene Plugintypen definiert, installiere Plugins findet (einschließlich denen von anderen Herstellern) und wie man diese einfach und portabel läd, indem man KService benutzt.''

== Lokalisation ==
;[[Development/Tutorials/Localization/Unicode (de)|Einführung in Unicode]]
:''Eine Einführung was Unicode ist und wie KDE Applikationen damit umgehen.''

; [[Development/Tutorials/Localization/i18n (de)|Beim Schreiben der Applikation an die Lokalisation denken]]
:''Diese Anleitung beschäftigt sich damit, was Lokalisation ist, warum sie wichtig ist und wie man sicherstellt, dass die eigene Applikation bereit ist, lokalisiert zu werden. Jeder Applikationsentwickler sollte das lesen.''

; [[Development/Tutorials/Localization/i18n Mistakes (de)|Häufige Fehler vermeiden]]
:''Es gibt einige häufige Fehler, die es verhindern, dass eine Applikation angemesssen übersetzt werden kann. Diese Anleitung zeigt diese Fehler auf und zeigt, wie man sie vermeidet.''

; [[Development/Tutorials/Localization/Language Change (de)|Mit Sprachänderungen umgehen]]
:''Wie man seiner Applikation beibringt beim nächsten Start oder zur Laufzeit eine andere Sprache zu benutzen.''

Development/Tutorials/Localization/Language Change (de)

2007-12-21T16:35:16Z

DrSlowDecay: Translated

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/Language Change}}

{{TutorialBrowser (de)|
series=Lokalisation|
name=Mit Sprachänderungen umgehen|
pre=[[../i18n (de)|Beim Schreiben von Applikationen an die Lokalisation denken]]|
}}

== Eine Option zum Ändern der Sprache hinzufügen ==
Für eine Benutzer kann es nützlich sein, die Sprache einer bestimmter Applikation zu ändern. Es ist glücklicherweise sehr einfach, eine solche Funktionalität zum eigenen Programm hinzuzufügen

Wenn Sie als Hauptfenster eine von KXmlGuiWindow abgeleitete Klasse benutzen, haben Sie bereits eine entsprechende programname.rc Datei bereitgestellt.

Verändern Sie diese einfach, damit sie folgendes beinhaltet:

<code>
<Menu name="help">
<Action name="switch_application_language"/>
</Menu>
</code>

Das ist alles. Jetzt haben Sie im "Help" Menü einen Eintrag "Switch Application Language" mit dem Sie die Sprache ändern können.

Der Benutzer muß jedoch die Applikation neu starten, damit der Sprachwechsel wirksam wird.

== Die GUI dynamisch ändern ==

Einen Schritt weiter geht die Option, die Sprache zur Laufzeit zu ändern, sobald der Benutzer dieses wünscht.

Das scheint ein sehr mühsames Unternehmen zu sein, da ein typisches Programm mehrere hundert übersetzbare Zeichenketten beinhalten kann, die neu übersetzt werden müssten doch glücklicherweise ist eine Menge Arbeit bereits erledigt, es muss nur noch richtig verknüpft werden.

Wenn die Sprache einer Applikation geändert wird, wird ein LanguageChanged {{Qt|QEvent}} ausgelöst und an jedes einzelne Widget gesendet. Die Idee ist, dass das Hauptfenster auf dieses Ereignis lauscht und der GUI und allen weiteren beteiltigten Elementen mitteilt, sich neu zu übersetzen.

Fügen Sie in ihrer von KXmlGuiWindow abgeleiteten Klasse einfach in die Header-Datei ein:

<code>
class MyWindow {
...
protected:
void changeEvent( QEvent * event );
void retranslateUi();
KAction *mSomeAction;
KAction *mQuitAction;
}
</code>

und in die Quelldatei:
<code>
MyWindow::MyWindow() : KXmlGuiWindow( 0 )
{
//setup the GUI. There should be no i18n calls here, but instead
//these calls should be in the retranslateUi() function
//Set up the actions in the GUI
mSomeAction = actionCollection()->addAction("something");
mSomeAction->setIcon(KIcon("some-action"));
connect(mSomeAction, SIGNAL(triggered(bool)), mWorkSpace, SLOT(newWorkSheet() ));

//KStandardActions need to be handled careful.
mQuitAction = NULL

retranslateUi();
// Use the KXmlGuiWindow class to setup the GUI
setupGUI(ToolBar | Keys | StatusBar | Create);
}

void MyWindow::changeEvent( QEvent * event )
{
if (event->type() == QEvent::LanguageChange) {
// This will setup the menu, toolbars etc again, using the new language
setupGUI(ToolBar | Keys | StatusBar | Create);
retranslateUi();
}
KXmlGuiWindow::changeEvent(event);
}

void MyWindow::retranslateUi()
{
// Set the window title
setPlainCaption( i18n( "My Window" ) );
// For custom actions, just set the text again
mMyAction->setText(i18n( "&Do Something..." ));
if(mQuitAction) {
//If we have already set this up before, create a new dummy action
// and grab what info we need from it
KAction *tmpQuitAction = KStandardAction::quit( NULL, NULL, NULL );
mQuitAction->setText(tmpQuitAction->text());
mQuitAction->setWhatsThis(tmpQuitAction->whatsThis());
mQuitAction->setToolTip(tmpQuitAction->toolTip());
delete tmpQuitAction;
} else
mQuitAction = KStandardAction::quit( this, SLOT( close() ), actionCollection() );
}

</code>

Auch wenn dies nicht sonderlich kompliziert ist, ist das alles was getan werden muss. Stellen Sie nur sicher, dass wann immer Sie eine neue Zeichenkette hinzufügen diese auch übersetzt werden kann.

Der Weg das in Qt zu bewerkstelligen ist, die Funktion retranslateUi() sowohl vom Konstruktor als auch vom LanguageChange Ereignis aufrufen zu lassen.

User:DrSlowDecay

2007-12-21T14:55:33Z

DrSlowDecay: New page: I'm doing some translation of tutorials in german.

I'm doing some translation of tutorials in german.

KDE TechBase:Contributors

2007-12-21T14:53:56Z

DrSlowDecay: /* German Team */

Welcome to the contributors page.

'''This site contains a list of ''active'' contributors. It should help to build teams which maintain KDE TechBase's content. If you have questions about KDE TechBase you can ask/email the corresponding person.'''

Please add yourself to the list where appropriate. If you are inactive, please remove yourself again.

== Administrators ==

This is a list of KDE TechBase administrators.

* [[User:Danimo|Danimo]]
* [[User:Dhaumann|Dhaumann]], <dhaumann at kde dot org>

== Reviewers and Article Writers ==

If you are continuously reviewing KDE TechBase changes or writing articles add yourself to the list.

* [[User:Dhaumann|Dhaumann]], <dhaumann at kde dot org>
* [[User:Milliams|Milliams]]
* name, <email>

== Translation Teams ==

KDE TechBase is [[Help:Wiki Translation|translated]] into many languages. If you translate pages please add yourself to the right translation team.

=== Chinese(simplified) Team ===
* [[User:Liangqi|Liangqi]], cavendish.qi at gmail dot com
* name, <email>

=== German Team ===
* [[User:DrSlowDecay|DrSlowDecay]], kde at metalhorde dot de
* name, <email>

=== Italian Team ===
* [[User:Thunder Teaser|Thunder Teaser]], totokid at gmail dot com
* name, <email>

=== ... Team ===
* name, <email>

Development/Tutorials/Localization/Language Change (de)

2007-12-21T14:49:03Z

DrSlowDecay: Page created and first translations

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/Language Change}}

{{TutorialBrowser (de)|
series=Localization|
name=Dealing with Language Changes|
pre=[[../i18n|Writing Applications With Localization in Mind]]|
}}

== Eine Option zum Ändern der Sprache hinzufügen ==

It can be extremely useful for a user to be able to change the language of a specific application. It is fortunately extremely easy to add such functionality to your program.

If you are using the KXmlGuiWindow class for your main window, then you will already have an associated programname.rc file for it.

Simply modify this file to contain:

<code>
<Menu name="help">
<Action name="switch_application_language"/>
</Menu>
</code>

And that is it! You will now have a Switch Application Language option in the Help menu.

However the user will need to restart the application for the changes to take effect.

== Die GUI dynamisch ändern ==

One step better is to change the language on the fly, as soon as the user has selected a new language.

This can seem a fairly daunting task, as a typical program can contain many hundreds of translatable strings that will need to be retranslated, but fortunately a lot of the work is already done for, and just needs to be connected together.

When the language of an application is changed, a LanguageChanged QEvent is sent to every single widget. The idea is that in the top level window you will listen for this event, tell the GUI to retranslate, tell the toolbars to retranslate, and then let any custom widgets clean up themselves.

So in your class that inherits from KXmlGuiWindow, add to the header file:

<code>
class MyWindow {
...
protected:
void changeEvent( QEvent * event );
void retranslateUi();
KAction *mSomeAction;
KAction *mQuitAction;
}
</code>

and to the source file:
<code>
MyWindow::MyWindow() : KXmlGuiWindow( 0 )
{
//setup the GUI. There should be no i18n calls here, but instead
//these calls should be in the retranslateUi() function
//Set up the actions in the GUI
mSomeAction = actionCollection()->addAction("something");
mSomeAction->setIcon(KIcon("some-action"));
connect(mSomeAction, SIGNAL(triggered(bool)), mWorkSpace, SLOT(newWorkSheet() ));

//KStandardActions need to be handled careful.
mQuitAction = NULL

retranslateUi();
// Use the KXmlGuiWindow class to setup the GUI
setupGUI(ToolBar | Keys | StatusBar | Create);
}

void MyWindow::changeEvent( QEvent * event )
{
if (event->type() == QEvent::LanguageChange) {
// This will setup the menu, toolbars etc again, using the new language
setupGUI(ToolBar | Keys | StatusBar | Create);
retranslateUi();
}
KXmlGuiWindow::changeEvent(event);
}

void MyWindow::retranslateUi()
{
// Set the window title
setPlainCaption( i18n( "My Window" ) );
// For custom actions, just set the text again
mMyAction->setText(i18n( "&Do Something..." ));
if(mQuitAction) {
//If we have already set this up before, create a new dummy action
// and grab what info we need from it
KAction *tmpQuitAction = KStandardAction::quit( NULL, NULL, NULL );
mQuitAction->setText(tmpQuitAction->text());
mQuitAction->setWhatsThis(tmpQuitAction->whatsThis());
mQuitAction->setToolTip(tmpQuitAction->toolTip());
delete tmpQuitAction;
} else
mQuitAction = KStandardAction::quit( this, SLOT( close() ), actionCollection() );
}

</code>

Although these is fairly complicated, that's about all that's needed. Just be careful whenever you add a new string somewhere that it can be translated.

The way it is done in Qt is to follow this pattern of having a retranslateUi() function that is called from both the constructor and from a LanguageChange event.

Development/Tutorials/Localization/Language Change

2007-12-21T14:47:35Z

DrSlowDecay: Added language navigation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/Language Change}}

{{TutorialBrowser|
series=Localization|
name=Dealing with Language Changes|
pre=[[../i18n|Writing Applications With Localization in Mind]]|
}}

== Adding an option to change the language ==

It can be extremely useful for a user to be able to change the language of a specific application. It is fortunately extremely easy to add such functionality to your program.

If you are using the KXmlGuiWindow class for your main window, then you will already have an associated programname.rc file for it.

Simply modify this file to contain:

<code>
<Menu name="help">
<Action name="switch_application_language"/>
</Menu>
</code>

And that is it! You will now have a Switch Application Language option in the Help menu.

However the user will need to restart the application for the changes to take effect.

== Dynamically changing the GUI ==

One step better is to change the language on the fly, as soon as the user has selected a new language.

This can seem a fairly daunting task, as a typical program can contain many hundreds of translatable strings that will need to be retranslated, but fortunately a lot of the work is already done for, and just needs to be connected together.

When the language of an application is changed, a LanguageChanged QEvent is sent to every single widget. The idea is that in the top level window you will listen for this event, tell the GUI to retranslate, tell the toolbars to retranslate, and then let any custom widgets clean up themselves.

So in your class that inherits from KXmlGuiWindow, add to the header file:

<code>
class MyWindow {
...
protected:
void changeEvent( QEvent * event );
void retranslateUi();
KAction *mSomeAction;
KAction *mQuitAction;
}
</code>

and to the source file:
<code>
MyWindow::MyWindow() : KXmlGuiWindow( 0 )
{
//setup the GUI. There should be no i18n calls here, but instead
//these calls should be in the retranslateUi() function
//Set up the actions in the GUI
mSomeAction = actionCollection()->addAction("something");
mSomeAction->setIcon(KIcon("some-action"));
connect(mSomeAction, SIGNAL(triggered(bool)), mWorkSpace, SLOT(newWorkSheet() ));

//KStandardActions need to be handled careful.
mQuitAction = NULL

retranslateUi();
// Use the KXmlGuiWindow class to setup the GUI
setupGUI(ToolBar | Keys | StatusBar | Create);
}

void MyWindow::changeEvent( QEvent * event )
{
if (event->type() == QEvent::LanguageChange) {
// This will setup the menu, toolbars etc again, using the new language
setupGUI(ToolBar | Keys | StatusBar | Create);
retranslateUi();
}
KXmlGuiWindow::changeEvent(event);
}

void MyWindow::retranslateUi()
{
// Set the window title
setPlainCaption( i18n( "My Window" ) );
// For custom actions, just set the text again
mMyAction->setText(i18n( "&Do Something..." ));
if(mQuitAction) {
//If we have already set this up before, create a new dummy action
// and grab what info we need from it
KAction *tmpQuitAction = KStandardAction::quit( NULL, NULL, NULL );
mQuitAction->setText(tmpQuitAction->text());
mQuitAction->setWhatsThis(tmpQuitAction->whatsThis());
mQuitAction->setToolTip(tmpQuitAction->toolTip());
delete tmpQuitAction;
} else
mQuitAction = KStandardAction::quit( this, SLOT( close() ), actionCollection() );
}

</code>

Although these is fairly complicated, that's about all that's needed. Just be careful whenever you add a new string somewhere that it can be translated.

The way it is done in Qt is to follow this pattern of having a retranslateUi() function that is called from both the constructor and from a LanguageChange event.

Development/Tutorials/Localization/i18n Build Systems (de)

2007-12-21T14:45:01Z

DrSlowDecay: Page created and first translations

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n Build Systems}}

{{TutorialBrowser (de)|

series=Lokalization|

name=Das l10n Modul von KDE erzeugen|

pre=[[../i18n (de)|Beim Schreiben von Applikationen an die Lokalisation denken]]|
next=[[../Language Change (de)|Sprachänderungen behandeln]]|
}}

== Zusammenfassung ==

Now that your application is ready to be localized, we next look at how to incorporate the necessary mechanisms into the CMake build system of your application.

First we'll explain the "theory" of the steps that need to happen from extracting message strings to installing the generated .po files. After that we'll look at how to implement those steps ([[#Theory: The xgettext toolchain]]). If your application is developed in KDE's subversion repository, many of those steps will happen automatically (see [[#handling i18n in KDE's subversion repository]]). Else you will want to read on in the [[#handling i18n in third party applications]] section.

== Theorie: Die xgettext toolchain ==

Making translations work consists of the following steps:
# Extract the translatable strings
# Merge the new or changed strings with existing translations
# Compile the translations into message catalogs
# Install the message catalogs
# Use the message catalogs in the application

=== Die Zeichenkette extrahieren ===

In this step, all the strings you marked as i18n()/ki18n()/etc. in your sources need to be collected into a translation template (.pot) file. Some translateable strings are also contained in .ui, .rc, or .kcfg files. Also tips-of-the-day need to be collected into the .pot file.

These steps are handled by {{path|xgettext}}, {{path|extractrc}}, and {{path|preparetips}} programs, respectively. In some cases you may also need {{path|extractattr}}.

=== Übersetzungen mischen ===

Generally, only a few translatable string will change at a time, in an application. Some will be removed, some will be added, some will be changed into different strings, and some will be moved around in the source files. These changes need to be reflected in the translations, but of course it would be a huge effort to redo the entire translation every time a string was changed. Rather the changes should be merged with the existing translations. This is the job of the {{path|msgmerge}} tool.

=== Übersetzungen kompilieren ===

In order to make message lookup fast, the .po files need to be compiled into so-called "message catalogs" (.mo / .gmo). This is done using the {{path|msgfmt}} tool.

=== Die Kataloge für Zeichenkette installieren ===

The compiled message catalogs need to be installed alongside the application. In KDE, the standard location for message catalogs is {{path|$KDEDIR/share/locale/xx/LC_MESSAGES/}}.

=== Die Kataloge für Zeichenketten benutzen ===

Finally, when the application is run, it needs to load the appropriate message catalog in order to be able to look up and show translated strings. In KDE applications, this is the job of the {{class|KLocale}} class, and in the great majority of cases happens automatically.

For some special cases, such as plugins, look at [[#Runtime Loading Of Catalogs]].

== i18n in KDE's subversion Repository behandeln ==

If your application is developed inside KDE's subversion repository, most of the steps outlined above are automated. In this case, generally, all you will need to do is provide a simple script called {{path|Messages.sh}}, which we will look at below.

In addition, if your top-level folder and .pot file have the same name, the svn2dist script will automatically include .po files when you use it to make a source tarball for your app.

Of course, for the curious, a more detailed account of what happens behind the scences is also provided.

=== Ein Messages.sh Skript schreiben ===

Basically, the only thing that is necessary to prepare and install translations for applications in KDE's subversion repository, is to provide information, which sources, ui-files or tips need to be translated. For this purpose, you write a small script called {{path|Messages.sh}} and place it in your sources. Here is an example with inline comments:

<code bash n>
#!bin/sh

# invoke the extractrc script on all .ui, .rc, and .kcfg files in the sources
# the results are stored in a pseudo .cpp file to be picked up by xgettext.
$EXTRACTRC `find . -name \*.rc -o -name \*.ui -o -name \*.kcfg` >> rc.cpp
# if your application contains tips-of-the-day, call preparetips as well.
$PREPARETIPS > tips.cpp
# call xgettext on all source files. If your sources have other filename
# extensions besides .cc, .cpp, and .h, just add them in the find call.
$XGETTEXT `find . -name \*.cc -o -name \*.cpp -o -name \*.h` -o $podir/APPNAME.pot
</code>

As you can see, this script contains only three actual lines of code, and not all may even be needed. The $XGETTEXT, $PREPARETIPS, $EXTRACTRC, and $podir environment variables are predefined, you do not need to worry about setting these. The only thing that you will need to do is to replace "APPNAME" with the name of your application (but see [[#Naming .pot Files]] for exceptions).

Try to make sure your Messages.sh script collects only those messages that are really needed. If in doubt, look at other Messages.sh files in the KDE subversion repository for inspiration, or - of course - ask.

=== Was geschieht hinter der Bühne ===

{{tip (de)|If your application is in the KDE code repository, all this happens automatically. If your code is not in the KDE repository, you must perform these steps yourself. See [[#handling i18n in third party applications]].}}

Periodically, the script {{path|extract-messages.sh}} (a.k.a. scripty) runs on the KDE server. This program basically calls all Messages.sh scripts in the repository with the appropriate parameters. The extracted messages are stored in template (.pot) files in the templates folder of the l10n module. See [[What Is Scripty]] for more information.

The KDE translation teams translate the messages and commit them into a messages folder corresponding to the language, which is further broken down by module. For example, German translated messages for konqueror are committed to {{path|l10n/de/messages/kdebase/konqueror.po}}.

When the l10n module is built, the .po files are compiled into a binary format for fast lookup and installed as .mo files to {{path|$KDEDIR/share/locale/xx/LC_MESSAGES/}}, where xx is the two-letter ISO 639 code for the language. These are called the message catalogs.

At runtime, the <tt>i18n(...)</tt> function, using the original string you coded, looks up the string in the message catalog of the user's desktop language and returns the translated string. If the message catalog is missing, or the specific string is not found, <tt>i18n(...)</tt> falls back to the original string in your code.

.desktop files in your project are handled separately. {{path|makemessages}} extracts strings, such as Name and Comment from the .desktop files and places them into a file named {{path|desktop_mmmm.pot}}, where mmmm is the module name, in the templates folder. Once translators have translated this file, makemessages inserts the translated strings back into the .desktop files. The list of strings extracted is in {{path|l10n/scripts/apply.cc}}. Here's the code that checks for them:

<code cppqt n>if (checkTag("Name", in, argc, argv, newFile))
continue;
if (checkTag("Comment", in, argc, argv, newFile))
continue;
if (checkTag("Language", in, argc, argv, newFile))
continue;
if (checkTag("Keywords", in, argc, argv, newFile))
continue;
if (checkTag("About", in, argc, argv, newFile))
continue;
if (checkTag("Description", in, argc, argv, newFile))
continue;
if (checkTag("GenericName", in, argc, argv, newFile))
continue;
if (checkTag("Query", in, argc, argv, newFile))
continue;
if (checkTag("ExtraNames", in, argc, argv, newFile))
continue;</code>

== i18n in Applikationen von dritten behandeln ==

If your application is developed outside of KDE's subversion repository, you need to take care of generating and installing message catalogs yourself. This is not too hard to do, but you should make sure you have a basic understanding of all steps involved, so you will probably want to read [[#Theory: The xgettext toolchain]], first.

Also, there is more than one way to deal with i18n in your application. We will outline one approach to do so for simple applications, but you may want to diverge from this, if you like to.

{{note (de)|The following improvements are needed in this section (or is this obsolete?):
How can messages for .desktop files be extracted?
How can translated .desktop messages be inserted back into .desktop files?}}

=== Allgemeine Überlegungen ===

The i18n generation process can roughly be divided into two steps:

# Extracting and merging messages
# Compiling and installing message catalogs

The first step really concerns the ''sources'', while the second step is a natural part of compiling and installing an application. Hence, while the second step should definitely be incorporated into the build system for your application (we assume CMake, here), there is no striking reason for the first step to be handled by the build system.

In fact, the extraction and merging of messages does not map well onto the CMake concept of out-of-source builds, and CMake can't provide too much help for this step, either.

Hence, in this tutorial, we will handle the first step with a standalone shell script, and only the second step will be handled by CMake.

=== Extrahieren und Mischen von Zeichenketten ===

If you have read the section [[#handling i18n in KDE's subversion repository]] you will know that in the KDE repository, message extraction and merging is handled by a simple script called Messages.sh, which is invoked by a script called {{path|extract-messages.sh}}. Outside of KDE's repository, you will need to take care of both parts, but fortunately, this is easy enough. Here's a sample script:

<code bash n>
#!/bin/sh
BASEDIR="../rkward/" # root of translatable sources
PROJECT="rkward" # project name
BUGADDR="http://sourceforge.net/tracker/?group_id=50231&atid=459007" # MSGID-Bugs
WDIR=`pwd` # working dir

echo "Preparing rc files"
cd ${BASEDIR}
# we use simple sorting to make sure the lines do not jump around too much from system to system
find . -name '*.rc' -o -name '*.ui' -o -name '*.kcfg' | sort > ${WDIR}/rcfiles.list
xargs --arg-file=${WDIR}/rcfiles.list extractrc > ${WDIR}/rc.cpp
# additional string for KAboutData
echo 'i18nc("NAME OF TRANSLATORS","Your names");' >> ${WDIR}/rc.cpp
echo 'i18nc("EMAIL OF TRANSLATORS","Your emails");' >> ${WDIR}/rc.cpp
cd ${WDIR}
echo "Done preparing rc files"

echo "Extracting messages"
cd ${BASEDIR}
# see above on sorting
find . -name '*.cpp' -o -name '*.h' -o -name '*.c' | sort > ${WDIR}/infiles.list
echo "rc.cpp" >> ${WDIR}/infiles.list
cd ${WDIR}
xgettext --from-code=UTF-8 -C -kde -ci18n -ki18n:1 -ki18nc:1c,2 -ki18np:1,2 -ki18ncp:1c,2,3 -ktr2i18n:1 \
-kI18N_NOOP:1 -kI18N_NOOP2:1c,2 -kaliasLocale -kki18n:1 -kki18nc:1c,2 -kki18np:1,2 -kki18ncp:1c,2,3 \
--msgid-bugs-address="${BUGADDR}" \
--files-from=infiles.list -D ${BASEDIR} -D ${WDIR} -o ${PROJECT}.pot || { echo "error while calling xgettext. aborting."; exit 1; }
echo "Done extracting messages"

echo "Merging translations"
catalogs=`find . -name '*.po'`
for cat in $catalogs; do
echo $cat
msgmerge -o $cat.new $cat ${PROJECT}.pot
mv $cat.new $cat
done
echo "Done merging translations"

echo "Cleaning up"
cd ${WDIR}
rm rcfiles.list
rm infiles.list
rm rc.cpp
echo "Done"
</code>

Of course you will want to adjust the variable definitions at the top, and - if needed - add code to extract tips-of-the-day or other additional strings.

The example script assumes that all .po files and the .pot file are kept in a single directory, which is appropriate for most projects.

=== Kompilieren und Installieren von Zeichenkettenkatalogen ===

Assuming you use the script from the previous section, you can place the following CMakeLists.txt in the directory containing the .po files:

<code>
FIND_PROGRAM(GETTEXT_MSGFMT_EXECUTABLE msgfmt)

IF(NOT GETTEXT_MSGFMT_EXECUTABLE)
MESSAGE(
"------
NOTE: msgfmt not found. Translations will *not* be installed
------")
ELSE(NOT GETTEXT_MSGFMT_EXECUTABLE)

SET(catalogname rkward)

ADD_CUSTOM_TARGET(translations ALL)

FILE(GLOB PO_FILES *.po)

FOREACH(_poFile ${PO_FILES})
GET_FILENAME_COMPONENT(_lang ${_poFile} NAME_WE)
SET(_gmoFile ${CMAKE_CURRENT_BINARY_DIR}/${_lang}.gmo)
ADD_CUSTOM_COMMAND(TARGET translations
COMMAND ${GETTEXT_MSGFMT_EXECUTABLE} --check -o ${_gmoFile} ${_poFile}
DEPENDS ${_poFile})
INSTALL(FILES ${_gmoFile} DESTINATION ${LOCALE_INSTALL_DIR}/${_lang}/LC_MESSAGES/ RENAME ${catalogname}.mo)
ENDFOREACH(_poFile ${PO_FILES})

ENDIF(NOT GETTEXT_MSGFMT_EXECUTABLE)
</code>

This iterates over all .po files in the directory, compiles them using msgfmt, and installs them to the standard location. You will want to change "catalogname" to the name of your application.

=== Übersetzungen erhalten ===

Now you just have to find translators to translate the extracted messages into the various languages. As your application gets used by more people, you will find that translators will volunteer to do this. Translated PO files then have to be stored in the po folder with the naming scheme <languagecode>.po.

== Sonderfälle (plugins, mehrere catalogs, etc.) ==

=== Kataloge zur Laufzeit laden ===

To have translations show up properly in an application, the name of the .pot file must match the name of the message catalog (.mo) file that your application will read at runtime. But what name will be used at runtime?

In general, it will be the value returned by <tt>{{class|KGlobal}}::instance()->instanceName()</tt>. But what will that be? The general rules for standalone applications are:
* the message catalog will default to the name of the application passed as the first argument to {{class|KAboutData}}
* if your code calls <tt>{{class|KLocale}}::setMainCatalog()</tt>, that name will be used instead
* if your code calls <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt>, the specified catalog will also be searched in addition to the main catalog

If your code does not call either of the {{class|KLocale}} methods mentioned above and your application is a plugin, it gets a little more complicated. If your code exports your plugin using the <tt>K_EXPORT_COMPONENT_FACTORY</tt> macro, like this:

<code cppqt>K_EXPORT_COMPONENT_FACTORY( libkhtmlkttsdplugin,
KGenericFactory<KHTMLPluginKTTSD>("khtmlkttsd") )</code>

then the catalog name will be the name passed in the {{class|KGenericFactory}} constructor - in the example above that woudl be <tt>khtmlkttsd</tt>. This is because the macro creates a {{class|Kinstance}} for you with the specified name.

However, some classes, such as <tt>KTextEditor</tt> create a <tt>KPart</tt> containing your component and the name passed in the macro is not used. In this case, you should call <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt> in the component's constructor.

If in doubt, the safest thing to do is to call <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt>.

{{tip|If you're not using the export macro for your plugin, you probably should be. See the API documentation of KGenericFactory for more information.}}

Calling <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt> if the catalog has already been inserted does nothing. However, calling <tt>{{class|KLocale}}::removeCatalog(const QString&)</tt> removes the catalog no matter how many times it has been inserted. Therefore, take care that you do not inadvertently remove the catalog when multiple components are sharing a single catalog. For example, the following sequence will break translations:

<code cppqt n>// Component A loads and uses catalog xyz by calling
insertCatalogue("xyz");
// Component B loads and also uses the same catalog.
insertCatalogue("xyz");
// component B unloads and calls
removeCatalogue("xyz")
// Component A now doesn't translate properly.</code>

Notice that a sequence such as above will occur automatically if both components A and B are loaded using the <tt>K_EXPORT_COMPONENT_FACTORY</tt> macro and pass the same name argument to the KGenericFactory constructor.

=== Benennung von .pot Dateien ===

The name that you settle on for both the .pot file and catalog should be governed by where your code resides. If it is a component of another application and resides in that application's source tree, you'll want to share the main catalog of the application.

If is a component of another application but resides elsewhere in the code repository, you will probably have to create a separate .pot, but keep in mind that .pot filenames must be unique across all of KDE.

If it is a component of another application, but resides in the source tree of a second application, you should share with the second application. For example, the KDE text-to-speach daemon (KTTSD) includes a plugin for embedded Kate in {{path|kdeaccessibility/kttsd}} source tree. Since the plugin is not installed unless kttsd is installed, it shares its catalog with kttsd and calls <tt>{{class|KLocale}}::insertCatalog("kttsd")</tt> to do this.

== Handbücher ==

Handbooks, which are written in docbook format, are handled different from applications. The translated Handbooks are committed into the l10n module in the docs folder under each language. In addition, the docs folder is broken down by module and application. For example, the German Kate Handbook is committed to the {{path|l10n/de/docs/kdebase/kate/}} folder. When compiled, the German Kate Handbook is installed to {{path|$KDEDIR/share/doc/HTML/de/kate/index.cache.bz2}}.

Note that it is up to each translation team to generate the translated Handbook when they feel it is complete.

[[Category:Programming]]

Development/Tutorials/Localization/i18n Build Systems

2007-12-21T14:37:23Z

DrSlowDecay: Added language navigation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n Build Systems}}

{{TutorialBrowser|

series=Localization|

name=Building KDE's l10n Module|

pre=[[../i18n|Writing Applications With Localization in Mind]]|
next=[[../Language Change|Dealing with language changes]]|
}}

== Abstract ==

Now that your application is ready to be localized, we next look at how to incorporate the necessary mechanisms into the CMake build system of your application.

First we'll explain the "theory" of the steps that need to happen from extracting message strings to installing the generated .po files. After that we'll look at how to implement those steps ([[#Theory: The xgettext toolchain]]). If your application is developed in KDE's subversion repository, many of those steps will happen automatically (see [[#handling i18n in KDE's subversion repository]]). Else you will want to read on in the [[#handling i18n in third party applications]] section.

== Theory: The xgettext toolchain ==

Making translations work consists of the following steps:
# Extract the translatable strings
# Merge the new or changed strings with existing translations
# Compile the translations into message catalogs
# Install the message catalogs
# Use the message catalogs in the application

=== Extracting the strings ===

In this step, all the strings you marked as i18n()/ki18n()/etc. in your sources need to be collected into a translation template (.pot) file. Some translateable strings are also contained in .ui, .rc, or .kcfg files. Also tips-of-the-day need to be collected into the .pot file.

These steps are handled by {{path|xgettext}}, {{path|extractrc}}, and {{path|preparetips}} programs, respectively. In some cases you may also need {{path|extractattr}}.

=== Merging translations ===

Generally, only a few translatable string will change at a time, in an application. Some will be removed, some will be added, some will be changed into different strings, and some will be moved around in the source files. These changes need to be reflected in the translations, but of course it would be a huge effort to redo the entire translation every time a string was changed. Rather the changes should be merged with the existing translations. This is the job of the {{path|msgmerge}} tool.

=== Compiling the translations ===

In order to make message lookup fast, the .po files need to be compiled into so-called "message catalogs" (.mo / .gmo). This is done using the {{path|msgfmt}} tool.

=== Installing the message catalogs ===

The compiled message catalogs need to be installed alongside the application. In KDE, the standard location for message catalogs is {{path|$KDEDIR/share/locale/xx/LC_MESSAGES/}}.

=== Using the message catalogs ===

Finally, when the application is run, it needs to load the appropriate message catalog in order to be able to look up and show translated strings. In KDE applications, this is the job of the {{class|KLocale}} class, and in the great majority of cases happens automatically.

For some special cases, such as plugins, look at [[#Runtime Loading Of Catalogs]].

== handling i18n in KDE's subversion repository ==

If your application is developed inside KDE's subversion repository, most of the steps outlined above are automated. In this case, generally, all you will need to do is provide a simple script called {{path|Messages.sh}}, which we will look at below.

In addition, if your top-level folder and .pot file have the same name, the svn2dist script will automatically include .po files when you use it to make a source tarball for your app.

Of course, for the curious, a more detailed account of what happens behind the scences is also provided.

=== Writing a Messages.sh script ===

Basically, the only thing that is necessary to prepare and install translations for applications in KDE's subversion repository, is to provide information, which sources, ui-files or tips need to be translated. For this purpose, you write a small script called {{path|Messages.sh}} and place it in your sources. Here is an example with inline comments:

<code bash n>
#!bin/sh

# invoke the extractrc script on all .ui, .rc, and .kcfg files in the sources
# the results are stored in a pseudo .cpp file to be picked up by xgettext.
$EXTRACTRC `find . -name \*.rc -o -name \*.ui -o -name \*.kcfg` >> rc.cpp
# if your application contains tips-of-the-day, call preparetips as well.
$PREPARETIPS > tips.cpp
# call xgettext on all source files. If your sources have other filename
# extensions besides .cc, .cpp, and .h, just add them in the find call.
$XGETTEXT `find . -name \*.cc -o -name \*.cpp -o -name \*.h` -o $podir/APPNAME.pot
</code>

As you can see, this script contains only three actual lines of code, and not all may even be needed. The $XGETTEXT, $PREPARETIPS, $EXTRACTRC, and $podir environment variables are predefined, you do not need to worry about setting these. The only thing that you will need to do is to replace "APPNAME" with the name of your application (but see [[#Naming .pot Files]] for exceptions).

Try to make sure your Messages.sh script collects only those messages that are really needed. If in doubt, look at other Messages.sh files in the KDE subversion repository for inspiration, or - of course - ask.

=== What's happening behind the scenes ===

{{tip|If your application is in the KDE code repository, all this happens automatically. If your code is not in the KDE repository, you must perform these steps yourself. See [[#handling i18n in third party applications]].}}

Periodically, the script {{path|extract-messages.sh}} (a.k.a. scripty) runs on the KDE server. This program basically calls all Messages.sh scripts in the repository with the appropriate parameters. The extracted messages are stored in template (.pot) files in the templates folder of the l10n module. See [[What Is Scripty]] for more information.

The KDE translation teams translate the messages and commit them into a messages folder corresponding to the language, which is further broken down by module. For example, German translated messages for konqueror are committed to {{path|l10n/de/messages/kdebase/konqueror.po}}.

When the l10n module is built, the .po files are compiled into a binary format for fast lookup and installed as .mo files to {{path|$KDEDIR/share/locale/xx/LC_MESSAGES/}}, where xx is the two-letter ISO 639 code for the language. These are called the message catalogs.

At runtime, the <tt>i18n(...)</tt> function, using the original string you coded, looks up the string in the message catalog of the user's desktop language and returns the translated string. If the message catalog is missing, or the specific string is not found, <tt>i18n(...)</tt> falls back to the original string in your code.

.desktop files in your project are handled separately. {{path|makemessages}} extracts strings, such as Name and Comment from the .desktop files and places them into a file named {{path|desktop_mmmm.pot}}, where mmmm is the module name, in the templates folder. Once translators have translated this file, makemessages inserts the translated strings back into the .desktop files. The list of strings extracted is in {{path|l10n/scripts/apply.cc}}. Here's the code that checks for them:

<code cppqt n>if (checkTag("Name", in, argc, argv, newFile))
continue;
if (checkTag("Comment", in, argc, argv, newFile))
continue;
if (checkTag("Language", in, argc, argv, newFile))
continue;
if (checkTag("Keywords", in, argc, argv, newFile))
continue;
if (checkTag("About", in, argc, argv, newFile))
continue;
if (checkTag("Description", in, argc, argv, newFile))
continue;
if (checkTag("GenericName", in, argc, argv, newFile))
continue;
if (checkTag("Query", in, argc, argv, newFile))
continue;
if (checkTag("ExtraNames", in, argc, argv, newFile))
continue;</code>

== handling i18n in third party applications ==

If your application is developed outside of KDE's subversion repository, you need to take care of generating and installing message catalogs yourself. This is not too hard to do, but you should make sure you have a basic understanding of all steps involved, so you will probably want to read [[#Theory: The xgettext toolchain]], first.

Also, there is more than one way to deal with i18n in your application. We will outline one approach to do so for simple applications, but you may want to diverge from this, if you like to.

{{note|The following improvements are needed in this section (or is this obsolete?):
How can messages for .desktop files be extracted?
How can translated .desktop messages be inserted back into .desktop files?}}

=== General considerations ===

The i18n generation process can roughly be divided into two steps:

# Extracting and merging messages
# Compiling and installing message catalogs

The first step really concerns the ''sources'', while the second step is a natural part of compiling and installing an application. Hence, while the second step should definitely be incorporated into the build system for your application (we assume CMake, here), there is no striking reason for the first step to be handled by the build system.

In fact, the extraction and merging of messages does not map well onto the CMake concept of out-of-source builds, and CMake can't provide too much help for this step, either.

Hence, in this tutorial, we will handle the first step with a standalone shell script, and only the second step will be handled by CMake.

=== Extracting and merging messages ===

If you have read the section [[#handling i18n in KDE's subversion repository]] you will know that in the KDE repository, message extraction and merging is handled by a simple script called Messages.sh, which is invoked by a script called {{path|extract-messages.sh}}. Outside of KDE's repository, you will need to take care of both parts, but fortunately, this is easy enough. Here's a sample script:

<code bash n>
#!/bin/sh
BASEDIR="../rkward/" # root of translatable sources
PROJECT="rkward" # project name
BUGADDR="http://sourceforge.net/tracker/?group_id=50231&atid=459007" # MSGID-Bugs
WDIR=`pwd` # working dir

echo "Preparing rc files"
cd ${BASEDIR}
# we use simple sorting to make sure the lines do not jump around too much from system to system
find . -name '*.rc' -o -name '*.ui' -o -name '*.kcfg' | sort > ${WDIR}/rcfiles.list
xargs --arg-file=${WDIR}/rcfiles.list extractrc > ${WDIR}/rc.cpp
# additional string for KAboutData
echo 'i18nc("NAME OF TRANSLATORS","Your names");' >> ${WDIR}/rc.cpp
echo 'i18nc("EMAIL OF TRANSLATORS","Your emails");' >> ${WDIR}/rc.cpp
cd ${WDIR}
echo "Done preparing rc files"

echo "Extracting messages"
cd ${BASEDIR}
# see above on sorting
find . -name '*.cpp' -o -name '*.h' -o -name '*.c' | sort > ${WDIR}/infiles.list
echo "rc.cpp" >> ${WDIR}/infiles.list
cd ${WDIR}
xgettext --from-code=UTF-8 -C -kde -ci18n -ki18n:1 -ki18nc:1c,2 -ki18np:1,2 -ki18ncp:1c,2,3 -ktr2i18n:1 \
-kI18N_NOOP:1 -kI18N_NOOP2:1c,2 -kaliasLocale -kki18n:1 -kki18nc:1c,2 -kki18np:1,2 -kki18ncp:1c,2,3 \
--msgid-bugs-address="${BUGADDR}" \
--files-from=infiles.list -D ${BASEDIR} -D ${WDIR} -o ${PROJECT}.pot || { echo "error while calling xgettext. aborting."; exit 1; }
echo "Done extracting messages"

echo "Merging translations"
catalogs=`find . -name '*.po'`
for cat in $catalogs; do
echo $cat
msgmerge -o $cat.new $cat ${PROJECT}.pot
mv $cat.new $cat
done
echo "Done merging translations"

echo "Cleaning up"
cd ${WDIR}
rm rcfiles.list
rm infiles.list
rm rc.cpp
echo "Done"
</code>

Of course you will want to adjust the variable definitions at the top, and - if needed - add code to extract tips-of-the-day or other additional strings.

The example script assumes that all .po files and the .pot file are kept in a single directory, which is appropriate for most projects.

=== Compiling and installing message catalogs ===

Assuming you use the script from the previous section, you can place the following CMakeLists.txt in the directory containing the .po files:

<code>
FIND_PROGRAM(GETTEXT_MSGFMT_EXECUTABLE msgfmt)

IF(NOT GETTEXT_MSGFMT_EXECUTABLE)
MESSAGE(
"------
NOTE: msgfmt not found. Translations will *not* be installed
------")
ELSE(NOT GETTEXT_MSGFMT_EXECUTABLE)

SET(catalogname rkward)

ADD_CUSTOM_TARGET(translations ALL)

FILE(GLOB PO_FILES *.po)

FOREACH(_poFile ${PO_FILES})
GET_FILENAME_COMPONENT(_lang ${_poFile} NAME_WE)
SET(_gmoFile ${CMAKE_CURRENT_BINARY_DIR}/${_lang}.gmo)
ADD_CUSTOM_COMMAND(TARGET translations
COMMAND ${GETTEXT_MSGFMT_EXECUTABLE} --check -o ${_gmoFile} ${_poFile}
DEPENDS ${_poFile})
INSTALL(FILES ${_gmoFile} DESTINATION ${LOCALE_INSTALL_DIR}/${_lang}/LC_MESSAGES/ RENAME ${catalogname}.mo)
ENDFOREACH(_poFile ${PO_FILES})

ENDIF(NOT GETTEXT_MSGFMT_EXECUTABLE)
</code>

This iterates over all .po files in the directory, compiles them using msgfmt, and installs them to the standard location. You will want to change "catalogname" to the name of your application.

=== Getting translations ===

Now you just have to find translators to translate the extracted messages into the various languages. As your application gets used by more people, you will find that translators will volunteer to do this. Translated PO files then have to be stored in the po folder with the naming scheme <languagecode>.po.

== Special cases (plugins, multiple catalogs, etc.) ==

=== Runtime Loading Of Catalogs ===

To have translations show up properly in an application, the name of the .pot file must match the name of the message catalog (.mo) file that your application will read at runtime. But what name will be used at runtime?

In general, it will be the value returned by <tt>{{class|KGlobal}}::instance()->instanceName()</tt>. But what will that be? The general rules for standalone applications are:
* the message catalog will default to the name of the application passed as the first argument to {{class|KAboutData}}
* if your code calls <tt>{{class|KLocale}}::setMainCatalog()</tt>, that name will be used instead
* if your code calls <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt>, the specified catalog will also be searched in addition to the main catalog

If your code does not call either of the {{class|KLocale}} methods mentioned above and your application is a plugin, it gets a little more complicated. If your code exports your plugin using the <tt>K_EXPORT_COMPONENT_FACTORY</tt> macro, like this:

<code cppqt>K_EXPORT_COMPONENT_FACTORY( libkhtmlkttsdplugin,
KGenericFactory<KHTMLPluginKTTSD>("khtmlkttsd") )</code>

then the catalog name will be the name passed in the {{class|KGenericFactory}} constructor - in the example above that woudl be <tt>khtmlkttsd</tt>. This is because the macro creates a {{class|Kinstance}} for you with the specified name.

However, some classes, such as <tt>KTextEditor</tt> create a <tt>KPart</tt> containing your component and the name passed in the macro is not used. In this case, you should call <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt> in the component's constructor.

If in doubt, the safest thing to do is to call <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt>.

{{tip|If you're not using the export macro for your plugin, you probably should be. See the API documentation of KGenericFactory for more information.}}

Calling <tt>{{class|KLocale}}::insertCatalog(const QString&)</tt> if the catalog has already been inserted does nothing. However, calling <tt>{{class|KLocale}}::removeCatalog(const QString&)</tt> removes the catalog no matter how many times it has been inserted. Therefore, take care that you do not inadvertently remove the catalog when multiple components are sharing a single catalog. For example, the following sequence will break translations:

<code cppqt n>// Component A loads and uses catalog xyz by calling
insertCatalogue("xyz");
// Component B loads and also uses the same catalog.
insertCatalogue("xyz");
// component B unloads and calls
removeCatalogue("xyz")
// Component A now doesn't translate properly.</code>

Notice that a sequence such as above will occur automatically if both components A and B are loaded using the <tt>K_EXPORT_COMPONENT_FACTORY</tt> macro and pass the same name argument to the KGenericFactory constructor.

=== Naming .pot Files ===

The name that you settle on for both the .pot file and catalog should be governed by where your code resides. If it is a component of another application and resides in that application's source tree, you'll want to share the main catalog of the application.

If is a component of another application but resides elsewhere in the code repository, you will probably have to create a separate .pot, but keep in mind that .pot filenames must be unique across all of KDE.

If it is a component of another application, but resides in the source tree of a second application, you should share with the second application. For example, the KDE text-to-speach daemon (KTTSD) includes a plugin for embedded Kate in {{path|kdeaccessibility/kttsd}} source tree. Since the plugin is not installed unless kttsd is installed, it shares its catalog with kttsd and calls <tt>{{class|KLocale}}::insertCatalog("kttsd")</tt> to do this.

== Handbooks ==

Handbooks, which are written in docbook format, are handled different from applications. The translated Handbooks are committed into the l10n module in the docs folder under each language. In addition, the docs folder is broken down by module and application. For example, the German Kate Handbook is committed to the {{path|l10n/de/docs/kdebase/kate/}} folder. When compiled, the German Kate Handbook is installed to {{path|$KDEDIR/share/doc/HTML/de/kate/index.cache.bz2}}.

Note that it is up to each translation team to generate the translated Handbook when they feel it is complete.

[[Category:Programming]]

Development/Tutorials (de)

2007-12-21T14:34:26Z

DrSlowDecay: Added two more translated chapters

Development/Tutorials/Localization/i18n Mistakes (de)

2007-12-21T14:29:45Z

DrSlowDecay: Page created and first translations

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n Mistakes}}

{{TutorialBrowser (de)|

series=Lokalisation|

name=Häufige Fehler vermeiden|

pre=[[../i18n (de)|Beim Schreiben der Applikation an die Lokalisation denken]]|

next=[[../i18n_Build_Systems (de)|i18n in das Build System einbinden]]|

}}

== Zusammenfassung ==
Es gibt ein paar häufige Fehler, die es unmöglich machen, eine Applikation angemessen zu übersetzen oder anderweitig zu lokalisieren. Das beinhaltet Pixel basierte Layouts, "Wort Puzzles" und Code, der Unicode Zeichen nicht adäquat behandelt. Diese Anleitung beschäftigt sich mit diesen Fällen und erklärt wie man sie verhindert.

== Falle #1: Pixel basierte Layouts ==

Englischer Text ist verglichen mit anderen Sprachen häufig sehr kompakt, der übersetze Text kann oft deutlich länger sein. Daher muß die Benutzerschnittstelle in der Lage sein, die Größe aufgrund der Länge der Übersetzung zur Laufzeit anzupassen. Kann sie das nicht, wird Text falsch angeordnet und/oder abgeschnitten.

Die Antwort darauf ist die Benutzung von Layoutmanagern. Qt bietet eine Anzahl von solchen Managern wie geschaffen für diesen Zweck. Darunter sind {{Qt|QHBoxLayout}}, {{Qt|QVBoxLayout}}, {{Qt|QGridLayout}} und {{Qt|QStackedLayout}}, alles Unterklassen von {{Qt|QLayout}}. Sie können auch eigene Klassen abgeleitet von {{Qt|QLayout}} erzeugen, das ist aber in der Regel nicht nötig.

Diese Layoutklassen kümmern sich um die Positionierung von Widgets zur Laufzeit, so macht es keinen Unterschied wie lang die übersetzten Zeichenketten sind. Die Benutzerschnittstelle passt sich entsprechend an. Für mehr Informationen siehe auch [http://doc.trolltech.com/qlayout.html QLayout (in englisch)].

== Falle #2: Wort Puzzles ==
Eine andere Sache ist es, zu beachten, nicht mehrere Teilsätze wie folgt zu verknüpfen:

<code cppqt>
QString msg=i18n("Do you want to replace ") +
oldFile+i18n(" with ") +
newFile + "?"</code>

Solche "Wort Puzzle" sind sehr schwer oder überhaupt nicht zu übersetzen. Das liegt daran, dass die Struktur eines Satzes in anderen Sprachen komplett anders sein kann und daher vom Übersetzer kontrolliert werden muss. Wenn die Reihenfolge der Worte und Satzteile wie oben festkodiert ist, kann der Übersetzer keine entsprechende Übersetzung erzeugen.

Zusätzlich zu diesem Problem erhhält der Übersetzung nur Teile des Satzes während der Übersetzung und muss daher raten, was zusammengehört.

Die Lösung ist denkbar einfach: Benutzen Sie <tt>%number</tt> Platzhalterersetzungen, die dem Übersetzer nicht nur gute Übersetzungen aufgrund der Möglichkeit den ganzen Satz zu sehen ermöglichen, sondern es ihm oder ihr auch erlaubt auch die Reihenfolge der Argumente frei zu ändern. Die Argumente selber werden als Extraparameter an <tt>i18n()</tt> übergeben.

Das obige Beispiel sollte daher korrekterweise folgendermaßen aussehen:

<code cppqt>
QString msg = i18n("Do you want to replace %1 with %2?",
oldFile, newFile)</code>

{{note (de)|Vermeiden Sie es etwas anderes als Zahlen oder Nomen mit dieser Methode einzufügen, da in einigen Sprachen die Übersetzung von den eingefügten Worten abhängt. Daher sollten möglichst komplette Sätze erzeugt werden.}}

Ein verwandter Fehler ist es, im zu übersetzenden Text keine Markup Tags wie or als Rich Text einzufügen. Nicht alle Sprachen benutzen solche Markups in gleicher Weise wie im Englischen, so es kann für den Übersetzer notwendig sein, diese ebenfalls zu "übersetzen".

Weiterhin sollten Zeichenketten, die häufig ändernde Zeichenketten enthalten (wie zum Beispiel Versionen) statt dessen als Platzhalter (siehe oben) eingefügt werden. Das verhindert unnötige Änderungen an den Zeichenketten, die die Übersetzer zwingen, die Übersetzungen zu überarbeiten.

Da KDE in mehr als 65 Sprachen übersetzt wird, kann die Änderung einer einzelenen Zeichenkette mindesten 65 Personen dazu zwingen, die Datei zu öffnen, die geänderte Zeichenkette zufinden, sorgfältig sicherzustellen, dass das wirklich das einzige ist, was sich geändert hat, die Neuübersetzung vorzunehemen, die Datei zu speichern und die geänderte Datei in das Repository hochzuladen. Alles in allem kann so eine kleine Änderung Stunden von Arbeit erzeugen, die einfach vermieden werden könnte.

== Falle #3: Fehlende Unicode Unterstützung ==
Immer dann wenn im Quellcode Datentypen oder Klassen für Zeichenketten benutzt werden, die kein Unicode unterstützen (z.B. <tt>char</tt> oder <tt>std::string</tt>), ist eine Übersetzung nicht mehr möglich.

Um das zu vermeiden, rufen Sie niemals QString::latin1() oder QString::ascii() für übersetze Zeichenketten auf. Das gilt auch für Informationen, die Sie von Benutzereingaben wie Passworten, URLs und Dateinamen erhalten. Benötigen Sie wirklich eine einfache <tt>char*</tt> Darstellung einer Zeichenkette benutzen Sie lieber QString::utf8().

{{note (de)|Für mehr Informationen über Zeichensätze und Unicode siehe [[Development/Tutorials/Localization/Unicode (de)|Einführung in Unicode]].}}

KIO slaves können Pfade und Dateinamen in UTF-8 verschlüsselt zur Verfügung stellen. Es liegt jedoch am Programmierer, entsprechend codierte Dateinamen an KIO Methoden zu übergeben. Der richtige Weg das zu tun, ist nicht zu raten, welches Codierungssystem das Dateisystem des Benutzers hat sondern statt dessen die Methoden QFile::encodeName() und QFile::decodeName() zu benutzen.

{{tip|Sie können testweise die UTF-8 Dateinamenunterstützung von KIO einschalten, indem Sie die Umgebungsvariable KDE_UTF8_FILENAMES (z.B. in ~/.bashrc) exportieren.}}

== Erfolg! ==
Wenn Sie diese drei häufigen Fehler verhindern, so wie es in dieser Anleitung beschrieben ist, wird Ihre Applikation von den verschiedenen KDE Übersetzerteams vollständig lokalisierbar sein und Ihre Applikation der Mehrheit der Menscheit zugänglich machen.

[[Category:Programming]]

Development/Tutorials/Localization/i18n Mistakes

2007-12-21T13:53:10Z

DrSlowDecay: Added language navigation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n Mistakes}}

{{TutorialBrowser|

series=Localization|

name=Avoiding Common Localization Pitfalls|

pre=[[../i18n|Writing Applications With Localization in Mind]]|

next=[[../i18n_Build_Systems|Incorporating i18n Into the Build System]]|

}}

== Abstract ==

There are a few common pitfalls that prevent applications from being properly translated or otherwise localized. These include using pixel based layouts, "word puzzles" and writing code that does not deal with Unicode characters properly. This tutorial covers each of these issues, explaining what to avoid and how to do it properly.

== Pitfall #1: Pixel Based Layouts ==

English text is often very compact compared to other languages where the translated text is often substantially longer. Therefore the interface much be able to adjust size to accommodate the length of translations provided at runtime. If it can't do this, then messages will end up misaligned and truncated.

The answer is to use layout managers. Qt provides a number of such layout managers pre-made for you. They include <tt>QHBoxLayout</tt>, <tt>QVBoxLayout</tt>, <tt>QGridLayout</tt> and <tt>QStackedLayout</tt>, all of which are subclasses of <tt>QLayout</tt>. You may also create your own <tt>QLayout</tt> based classes, but this is generally not needed.

These layout classes manage the pixel positioning of widgets for you at runtime, so no matter what the size of the translated strings your interface will adjust properly. For more information look at the documentation for [[http://doc.trolltech.com/qlayout.html QLayout]].

== Pitfall #2: Word Puzzles ==

Another thing to be aware of is to not concatenate pieces of sentences together like this:

<code cppqt>
QString msg=i18n("Do you want to replace ") +
oldFile+i18n(" with ") +
newFile + "?"</code>

Such "word puzzles" are very hard or even impossible to translate. This is because the structure of the sentence will often be completely different in another language and thus must be controlled by the translator. When the order of words and phrases is hard-coded as in the above example, the translator can not create a proper translation.

Adding to this problem, a translator will only see parts of the sentence while translating and will have to guess at what belongs together.

The solution thankfully is quite simple: use <tt>%number</tt> placeholder substitution, which lets the translators not only make good translations because they can see the entirety of the sentence during translation, but which also lets them change the order of the arguments freely. The arguments themselves are passed as extra parameters to <tt>i18n()</tt>.

The above example written properly would then look like this:

<code cppqt>
QString msg = i18n("Do you want to replace %1 with %2?",
oldFile, newFile)</code>

{{note|Avoid inserting anything other than numbers or nouns with this method, since in some languages the translation depends on the inserted words. It is therefore best to create strings that are as complete sentences as possible.}}

A related mistake is not including markup tags in rich text, such as or , in the translatable string. Not all languages use such markup in an identical fashion to English and so it is necessary for the translator to be able to "translate" the markup accordingly as well.

Similarly, messages that contain a version string or other often changing parts should be inserted by placeholders into the message. This prevents unnecessary changes that cause the translators to have to change the translated messages as well.

Since KDE is translated into more than 65 languages a single string change causes at least 65 people to open the file, find the changed message, look carefully if this is the only thing that has changed, change the translation, save the file again and commit the changed file into the code repository. All in all such a small change might create hours of work which could be easily avoided.

== Pitfall #3: Lack of Unicode Support ==

Whenever there is source code that handles strings using a datatype (such as <tt>char</tt>) or class (such as <tt>std::string</tt>) that can not handle Unicode, translations will break.

To avoid this, never call QString::latin1() or QString::ascii() on translated strings. This also applies to information resulting from user input such as passwords, URLs and filenames. If you really need a plain <tt>char*</tt> representation of a string, it is better to use QString::utf8().

{{note|For more information on character sets and Unicode, see the [[Development/Tutorials/Localization/Unicode|Unicode tutorial]].}}

KIO slaves may also provide paths and file names encoded using UTF-8. It is up to the programmer, however, to take care of passing properly encoded filenames to any KIO method in question. The correct way to do this is not to guess at user's filesystem encoding but to use QFile::encodeName() and QFile::decodeName() instead.

{{tip|You can turn KIO's UTF-8 file name support on for testing by exporting the KDE_UTF8_FILENAMES environment variable in your shell's startup file (e.g. ~/.bashrc).}}

== Success! ==

If you avoid the three common categories of pitfalls detailed in this tutorial, your application should be fully localizable by the various KDE translation teams around the world and open up your application to the majority of people on the planet.

[[Category:Programming]]

Development/Tutorials/Localization/i18n (de)

2007-12-21T13:51:17Z

DrSlowDecay: Translated the rest

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n}}

{{TutorialBrowser (de)|

series=Lokalisation|

pre=[[../Unicode (de)|Introduction to Unicode]] ist empfohlen wenn auch nicht notwendig|

name=Beim Applikationen schreiben an die Lokalisation denken|

next=[[../i18n_Mistakes (de)|Häufige Fehler vermeiden]]|

}}

== Zusammenfassung ==

Eine breite Schar an Benutzern und Entwicklern zu erreichen erfordert, dass Ihre Software übersetzt werden kann und sich auch anderweitig an sprachliche und kulturelle Gegebenheiten desjenigen anpassen kann, der Ihre Applikation benutzt. Das ist die Aufgabe von Lokalisation und diese Anleitung leitet Sie durch die grundlegenden Schritte, Ihre Applikation lokalisierungsfähig zu machen.

== Was ist Internationalisation and Lokalisation? ==

Internationalisation, oder i18n ('i', gefolgt von 18 Buchstaben und dann ein 'n'), bezeichnet den Prozess, Ihre Applikation so zu schreiben, dass sie in jeder beliebigen Sprache und Kultur laufen kann. Dabei müssen folgende Dinge berücksichtigt werden:
* Textmitteilungen, die dem Benutzer mitgeteilt werden
* Dateneingabe vom Benutzer, Dateien und anderen Quellen
* Das Format von Datum, Zahlen, Währungen, etc.

Lokalisation, oder l10n ('l' gefolgt von 10 Zeichen und dann ein 'n') ist der Prozess, eine internationalisierte Applikation an bestimmte lokale Gegebenheiten anzupassen.

Im allgemeinen internationalisieren Programmierer ihre Applikationen und Übersetzerteams lokalisieren sie.

== Warum ist das wichtig? ==

KDE Entwicklung findet primär in Englisch statt, da dies eine breite Entwickler- und Übersetzerschaft erreicht. Englisch ist jedoch nicht die Muttersprache der meisten Menschen auf der Welt. Tatsächlich sprechen weniger als 8% der Menschheit Englisch und weniger als 5% sprechen es als Muttersprache. Auch im Internet benutzen nur 35% der Menschen die online sind Englisch als primäre Sprache und je mehr Teile der Welt an das Internet angeschlossen werden, desto geringer wird dieser Anteil werden. Zusätzlich benutzen die meisten sprachen, alleine 9 der 10 häufigsten, nicht-ASCII Zeichen in ihrer geschriebenen Form. Daher ist es einfach zu erkennen, warum es notwendig ist, Software zu lokalisieren.

Als internationales Projekt das den gesamten Globul umspannt, ist diese Lokalisation ein wichtiges Gut der KDE Kultur. Tatsächlich entwickeln viele KDE Entwickler ihre Applikationen in Englisch benutzen jedoch ihren KDE-Desktop in der jeweils lokalisierten Version.

== Übersetzbaren Code mit i18n() ==
Um sicherzustellen, dass Ihre Applikation für eine Lokalisation vorbereitet ist, müssen Sie einigen wenigen einfachen Regeln folgen. Alle für Benutzer sichtbaren Zeichenketten Ihrer Applikation sollten übersetzt werden, bevor Sie auf dem Bildschirm des Benutzers dargestellt werden, ausgenommen davon sind Debug-Ausgaben, Konfigurationsdaten und andere ähnliche Textdaten.

KDE stellt als Teil von <tt>libkdecore</tt> die Klasse {{Class|KLocale}} zur Verfügung, um die technischen Aspekte der Lokalisierung zu erledigen. KLocale macht es Entwicklern so einfach wie möglich, ihren Code i18n fähig zu machen, dennoch bleiben einige Dinge, die Sie als Entwickler beachten müssen, damit die Applikation in anderen Sprachen und Ländern eingesetzt werden kann.

Zugriff auf das globale <tt>KLocale</tt> Objekt wird über <tt>KGlobal::locale()</tt> zur Verfügung gestellt. Dieses <tt>Klocale</tt> Objekt wird automatisch von {{Class|KInstance}} erzeugt und kümmert sich um alle i18n betreffenden Einstellungen. Beim Verlassen der Applikation wird das Objekt automatisch gelöscht.

Übersetzungen werden von der i18n(const char*) Methode von {{Qt|QString}} ermöglicht, definiert in <tt>klocalizedstring.h</tt>. Darin müssen alle Zeichenketten, die dargestellt werden, eingebettet werden. Der von <tt>i18n()</tt> zurückgegebene QString ist die (wenn nötig) übersetze Zeichenkette. Dadurch werden übersetzbare Widgets so einfach möglich, wie das nachfolgende Beispiel zeigt:

<code cppqt>
#include <klocalizedstring.h>
[...]
QPushButton* myButton = new QPushButton(i18n("Translate this!"));</code>

Die native Unicode-Unterstützung von QString stellt sicher, das alle Übersetzungen richtig dargestellt werden. Alle Zeichenkettenbehandlungen Ihrer Applikation sollten daher QString benutzen.

{{tip|Wenn die Zeichenkette, die übersetzt werden soll, irgendwelche nicht-UTF8 Zeichen enthält, benutzen Sie die Methode utf8() um ein char* zu erhalten.}}

=== ki18n ===
Die <tt>i18n()</tt> Methoden benötigt ein existierendes {{Class|KInstance}} (z.B. ein {{Class|KApplication}}) Objekt. Für Zeichenketten die vor der Erzeugung erstellt werden muss eine andere Methode zur Verfügung gestellt werden: <tt>ki18n</tt>. Diese erlaubt es, Zeichenketten zur späteren übersetzung zu markieren. ki18n() gibt ein {{Class|KLocalizedString}} zurück, welches letztlich in ein {{Qt|QString}} konvertiert wird (also schließlich übersetzt wird), nachdem KInstance erzeugt wurde. Dabei wird dessen toString() Methode benutzt.

ki18n() wird typischerweise in Zeichenketten benutzt, die an {{Class|KAboutData}} übergeben werden, da dieses von {{Class|KApplication}} erzeugt wird. Außerhalb dieser Sonderfälle kann man immer ohne Bedenken i18n() benutzen, wenn man sicher ist, dass dieser Code ausgeführt nachdem KApplication oder eine andere {{Class|KInstance}} konstruiert wurde.

=== Kontext hinzufügen ===
Es gibt eine erweiterte Version von <tt>i18n()</tt>, <tt>i18nc()</tt>, die zwei
<tt>const char*</tt> Argumente übernimmt. Das erste Argument ist eine zusätzliche Beschreibung des Kontext, in dem die zweite Zeichenkette übersetzt wird. Die erste Zeichenkette wird dabei benutzt, um zur Laufzeit die zum Kontext passende Übersetzung finden und wird den Übersetzer angezeigt, um diesen zu helfen, die Bedeutung der Zeichenkette zu verstehen.

Benutzen Sie <tt>i18nc()</tt> immer dann, wenn der Sinn des Textes mehrdeutig sein kann ohne die Angabe eines Kontext. Stellen Sie sich zum Beispiel das Kontextmenü eines Dateimanagers vor, in dem ein Eintrag namens "View" existiert, die einen Betrachter für die momentan ausgewählte Datei startet. In diesem Kontext ist "View" ein Verb. In der gleichen Applikation könnte jetzt aber auch ein Menüeintrag namens "View" existieren und in diesem Kontext ein Nomen sein. In der englisches Version dieser Applikation würde jetzt alles in Ordnung aussehen, doch in den meisten anderen Spreachen wären diese beiden "View" Zeichenketten nicht gleich.

Zusätzlich benötigen Übersetzer bei ihrer Arbeit manchmal zusätzliche Hilfe zu verstehen, worauf sich der aktuelle Text gerade bezieht.

Im obigen Beispiel des Dateimanagers könnte man daher schreiben:

<code cppqt>contextMenu->addAction(i18nc("verb, to view something", "View"));
viewMenu->addAction(i18nc("noun, the view", "View"));</code>

Jetzt wären diese beiden Zeichenketten angemessen zu übersetzen, sowohl für den menschlichen Übersetzung als auch zur Laufzeit für KLocale.

Benutzen Sie diese Form von i18n immer dann, wenn die Zeichenkette, die übersetzt werden soll, kurz ist oder die Bedeutung schwer zu entscheiden ist, wenn des Kontext nicht bekannt ist. Zum Beispiel:

<code cppqt>QString up = i18nc("Go one directory up in the hierarchy", "Up");
QString relation = i18nc("A person's name and their familial relationship to you.", "%1 is your %2", name, relationship);</code>

{{note (de)|Es gibt auch eine ki18nc("context","text") Methode, die Kontext zu Zeichenkette hinzufügt, die vor {{Class|KInstance}} erzeugt werden (siehe oben). Es liefert ein {{Class|KLocalizedString}} zurück, damit die Methode toString() hinterher daraus einen QString erzeugen kann.}}

Kontext kann auch in Formularen, die mit dem Qt Designer erzeugt werden, hinzugefügt werden. Jedes Widget Label, einschließlich tooltips und whatsthis Texte haben ein "comment" Attribut, welches den gleichen Zweck wie das erste Argument von <tt>i18nc()</tt> hat.

=== Standard Kontext für häufige Ausdrücke ===

Es folgt eine Tabelle, die einige häufige Worte und Satzfragmente im Englischen und den entsprechend zu benutzenden Kontext, der benutzt werden muß, um die entsprechende Übersetzung in andere Sprachen zu bestimmen, auflistet.

{|
|+ Standard Kontexte
|-
! Satzfragment !! Kontext !! i18nc Call !! Beispiel
|-
| Busy || Refering to a person || <tt>i18nc("A person is busy", "Busy")</tt>
|-
| Busy || Refering to a thing || <tt>i18nc("A thing is busy", "Busy")</tt>
|-
| Color || Color mode, as opposed to Grayscale || <tt>i18nc("Color mode", "Color")</tt>
|-
| Creator || Refering to a person || <tt>i18nc("A person who creates", "Creator")</tt>
|-
| Creator || Refering to software || <tt>i18nc("Software", "Creator")</tt>
|-
| Display || Refering to hardware || <tt>i18nc("Hardware display", "Display")</tt>
|-
| Editor || Refering to a person || <tt>i18nc("A person who edits", "Editor")</tt>
|-
| Editor || Refering to software || <tt>i18nc("Software", "Editor")</tt>
|-
| Line || Refering to drawing || <tt>i18nc("Draw a line", "Line")</tt>
|-
| Line || Refering to text || <tt>i18nc("Line of text", "Line")</tt>
|-
| Name || Refering to a name of thing || <tt>i18nc("A thing's name", "Name") || In theme change dialog: i18nc("Theme name", "Name")</tt>
|-
| Name || Refering to first name and last name of person || <tt>i18nc("Person's first and last name", "Name") || In KAddessbook contact edit dialog: i18nc("Person's first and last name", "Name")</tt>
|-
| No || Answer to a question || <tt>i18nc("Answer to a question", "No")</tt>
|-
| No || Availability of a thing || <tt>i18nc("Availability", "No")</tt>
|-
| (Re)load || (Re)load a document, medium etc. || <tt>i18nc("(Re)load a document", "(Re)load")</tt>
|-
| (Re)load || (Re)start a program, daemon etc. || <tt>i18nc("(Re)start a program", "(Re)load")</tt>
|-
| Title || Refering to a person || <tt>i18nc("A person's title", "Title")</tt>
|-
| Title || Refering to a thing || <tt>i18nc("A thing's title", "Title")</tt>
|-
| Volume || Refering to sound || <tt>i18nc("Sound volume", "Volume")</tt>
|-
| Volume || Refering to a filesystem || <tt>i18nc("Filesystem volume", "Volume")</tt>
|-
| Volume || Refering to books || <tt>i18nc("Book volume", "Volume")</tt>
|-
| Yes || Answer to a question || <tt>i18nc("Answer to a question", "Yes")</tt>
|-
| Yes || Availability of a thing|| <tt>i18nc("Availability", "Yes")</tt>
|}

=== Plural ===
Plural wird von Sprache zu Sprache unterschiedlich behandelt. Viele Sprachen haben einen unterschiedlichen Plural für 2, 10, 20, 100 usw. Wennn die Zeichenkette, die übersetzt werden soll sich auf mehr als ein Item beziehen kann, müssen Sie eine dritte Form von <tt>i18n</tt> benutzen, nämlich <tt>i18np()</tt>. Die Funktion übernimmt die Singular- und Pluralversion in Englisch als erste beide Argumebnte, gefolgt von beliebigen Argumenten, die ersetzt werden sollen. Davon muß jedoch mindestens eines eine Ganzzahl sein. Beispiel:

<code cppqt>msgStr = i18np("1 image in album %2", "%1 images in album %2", numImages, albumName);</code>

<tt>i18np()</tt> wird enstrechend der in der Sprache des Benutzers notwenidigen Fälle erweitert. Im Englischen gibt es nur diese beiden Formen, während in anderen Sprachen mehrere existieren können, abhängig vom ersten Ganzzahlargument.

Beachten Sie, dass diese Form auch dann benutzt werden sollte, wenn die Zeichenkeitte sich immer auf mehrere Items bezieht, da manche Sprachen auch in anderen Fällen Singular (typischerweise bei 21, 32, etc.) benutzen. Dieser Code:

<code cppqt>i18n("%1 files were deleted", numFilesDeleted);</code>

ist daher falsch und sollte lauten:

<code cppqt>i18np("1 file was deleted",
"%1 files were deleted",
numFilesDeleted);</code>

Um neben Pluralangaben auch einen Kontext zu übergeben, benutzen Sie <tt>i18ncp</tt> wie in diesem Beispiel:

<code cppqt>i18ncp("Personal file", "1 file", "%1 files", numFiles);</code>

== Datum und Zahlen formatieren ==

When dem Benutzer Zahlen angezeigt werden, muss Ihr Programm die richtigen Dezimaltrennzeichen, Tausendertrennzeichen und Währungssymbol (falls überhaupt) darstellen. Diese Sysmbole unterschieden sich von Region zu Region. In englischsprachigen Ländern wird ein Punkt (.) benutzt um den gebrochenen Teil einer Zahl anzuzeigen (z.B. 12.5), während einige europäische Länder ein Komma (,) benutzen (z.B. 12,5). Es folgt eine Tabelle, die die Funktionen zusammenfasst, die Ihnen dabei hilft, diese lokalen Konventionen korrekt zu behandeln.

{|
|+ Funktionen um Zahlen zu formatieren
|-
! Formatiert ein(e).. !! Von einem.. !! Funktions Prototyp
|-
| Zahl || String || <pre>QString formatNumber( const QString & numStr )</pre>
|-
| Zahl || Integer, double || <pre>formatNumber( double num,
int precision = -1 )</pre>
|-
| Währung || String || <pre>formatMoney( const QString & numStr )</pre>
|-
| Währung || Zahl || <pre>formatMoney( double num,
const QString & currency,
int digits = -1 )</pre>
|-
| Datum || String || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Uhrzeit || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false)</pre>
|-
| Datum und Uhrzeit || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat = true,
bool includeSecs = false )</pre>
|}

Ähnliche Funktionen existieren umd Informationen zu lesen, die der Benutzer zur Laufzeit in seinem lokalisierten Format eingibt, z.B. readNumber() oder readMoney().

== Kalender ==

Applikationen zu entwickeln, die sich mit Datum und Zeit beschäftigen, zum Beispiel Kalender, ist ein sehr komplexes Gebiet. Nicht nur Zeichenketten die ein Datum oder eine Uhrzeit beinhalten müssen lokal angepasst werden, man muss auch andere Aspekte bedenken, wie zum Beispiel:
* Welcher Dag in der Woche der erste ist (cf int weekStartDay())
* Wieviele Monate in einem Jahr sind
* "Ära"-basierte Kalender
* Ob ein 24-Stunden Zeitformat benutzt wird (cf bool use12Clock())

KLocale stellt neben anderen diese Methoden zur verfügung:

{|
|+ Kalenderdaten Funktionen
|-
! Formatiert ein(e).. !! von einem.. !! Funktions Prototyp
|-
| Datum || QDate || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Uhrzeit || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false )</pre>
|-
| Datum und Uhrzeit || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat=true,
bool includeSecs=false )</pre>
|}

{{improve (de)|Mehr Informationen für verschiedene Kalendersysteme geben}}

== Häufige Fallen vermeiden ==
Es gibt eine Reihe von häufigen Problemen die es unmöglich machen, eine Applikation angemessen zu lokalisieren. Im nächsten Kapitel [[../i18n Mistakes (de)|Häufige Fehler in der Lokalisation vermeiden]] lernen Sie mehr darüber und wie man solche Fehler vermeidet.

{{note (de)|Dank geht an Lukáš Tinkl, Matthias Kiefer und Gary Cramblitt für die Originalversion dieser Anleitung.}}

[[Category:Programming]]

KDE TechBase:Contributors

2007-12-21T12:36:02Z

DrSlowDecay: /* German Team */

Welcome to the contributors page.

'''This site contains a list of ''active'' contributors. It should help to build teams which maintain KDE TechBase's content. If you have questions about KDE TechBase you can ask/email the corresponding person.'''

Please add yourself to the list where appropriate. If you are inactive, please remove yourself again.

== Administrators ==

This is a list of KDE TechBase administrators.

* [[User:Danimo|Danimo]]
* [[User:Dhaumann|Dhaumann]], <dhaumann at kde dot org>

== Reviewers and Article Writers ==

If you are continuously reviewing KDE TechBase changes or writing articles add yourself to the list.

* [[User:Dhaumann|Dhaumann]], <dhaumann at kde dot org>
* name, <email>

== Translation Teams ==

KDE TechBase is [[Help:Wiki Translation|translated]] into many languages. If you translate pages please add yourself to the right translation team.

=== German Team ===
* DrSlowDecay, kde at metalhorde dot de
* name, <email>

=== ... Team ===
* name, <email>

Development/Tutorials/Localization/i18n (de)

2007-12-21T12:30:38Z

DrSlowDecay: More Translation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n}}

{{TutorialBrowser (de)|

series=Lokalisation|

pre=[[../Unicode (de)|Introduction to Unicode]] ist empfohlen wenn auch nicht notwendig|

name=Beim Applikationen schreiben an die Lokalisation denken|

next=[[../i18n_Mistakes (de)|Häufige Fehler vermeiden]]|

}}

== Zusammenfassung ==

Eine breite Schar an Benutzern und Entwicklern zu erreichen erfordert, dass Ihre Software übersetzt werden kann und sich auch anderweitig an sprachliche und kulturelle Gegebenheiten desjenigen anpassen kann, der Ihre Applikation benutzt. Das ist die Aufgabe von Lokalisation und diese Anleitung leitet Sie durch die grundlegenden Schritte, Ihre Applikation lokalisierungsfähig zu machen.

== Was ist Internationalisation and Lokalisation? ==

Internationalisation, oder i18n ('i', gefolgt von 18 Buchstaben und dann ein 'n'), bezeichnet den Prozess, Ihre Applikation so zu schreiben, dass sie in jeder beliebigen Sprache und Kultur laufen kann. Dabei müssen folgende Dinge berücksichtigt werden:
* Textmitteilungen, die dem Benutzer mitgeteilt werden
* Dateneingabe vom Benutzer, Dateien und anderen Quellen
* Das Format von Datum, Zahlen, Währungen, etc.

Lokalisation, oder l10n ('l' gefolgt von 10 Zeichen und dann ein 'n') ist der Prozess, eine internationalisierte Applikation an bestimmte lokale Gegebenheiten anzupassen.

Im allgemeinen internationalisieren Programmierer ihre Applikationen und Übersetzerteams lokalisieren sie.

== Warum ist das wichtig? ==

KDE Entwicklung findet primär in Englisch statt, da dies eine breite Entwickler- und Übersetzerschaft erreicht. Englisch ist jedoch nicht die Muttersprache der meisten Menschen auf der Welt. Tatsächlich sprechen weniger als 8% der Menschheit Englisch und weniger als 5% sprechen es als Muttersprache. Auch im Internet benutzen nur 35% der Menschen die online sind Englisch als primäre Sprache und je mehr Teile der Welt an das Internet angeschlossen werden, desto geringer wird dieser Anteil werden. Zusätzlich benutzen die meisten sprachen, alleine 9 der 10 häufigsten, nicht-ASCII Zeichen in ihrer geschriebenen Form. Daher ist es einfach zu erkennen, warum es notwendig ist, Software zu lokalisieren.

Als internationales Projekt das den gesamten Globul umspannt, ist diese Lokalisation ein wichtiges Gut der KDE Kultur. Tatsächlich entwickeln viele KDE Entwickler ihre Applikationen in Englisch benutzen jedoch ihren KDE-Desktop in der jeweils lokalisierten Version.

== Übersetzbaren Code mit i18n() ==
Um sicherzustellen, dass Ihre Applikation für eine Lokalisation vorbereitet ist, müssen Sie einigen wenigen einfachen Regeln folgen. Alle für Benutzer sichtbaren Zeichenketten Ihrer Applikation sollten übersetzt werden, bevor Sie auf dem Bildschirm des Benutzers dargestellt werden, ausgenommen davon sind Debug-Ausgaben, Konfigurationsdaten und andere ähnliche Textdaten.

KDE stellt als Teil von <tt>libkdecore</tt> die Klasse {{Class|KLocale}} zur Verfügung, um die technischen Aspekte der Lokalisierung zu erledigen. KLocale macht es Entwicklern so einfach wie möglich, ihren Code i18n fähig zu machen, dennoch bleiben einige Dinge, die Sie als Entwickler beachten müssen, damit die Applikation in anderen Sprachen und Ländern eingesetzt werden kann.

Zugriff auf das globale <tt>KLocale</tt> Objekt wird über <tt>KGlobal::locale()</tt> zur Verfügung gestellt. Dieses <tt>Klocale</tt> Objekt wird automatisch von {{Class|KInstance}} erzeugt und kümmert sich um alle i18n betreffenden Einstellungen. Beim Verlassen der Applikation wird das Objekt automatisch gelöscht.

Übersetzungen werden von der i18n(const char*) Methode von {{Qt|QString}} ermöglicht, definiert in <tt>klocalizedstring.h</tt>. Darin müssen alle Zeichenketten, die dargestellt werden, eingebettet werden. Der von <tt>i18n()</tt> zurückgegebene QString ist die (wenn nötig) übersetze Zeichenkette. Dadurch werden übersetzbare Widgets so einfach möglich, wie das nachfolgende Beispiel zeigt:

<code cppqt>
#include <klocalizedstring.h>
[...]
QPushButton* myButton = new QPushButton(i18n("Translate this!"));</code>

Die native Unicode-Unterstützung von QString stellt sicher, das alle Übersetzungen richtig dargestellt werden. Alle Zeichenkettenbehandlungen Ihrer Applikation sollten daher QString benutzen.

{{tip|Wenn die Zeichenkette, die übersetzt werden soll, irgendwelche nicht-UTF8 Zeichen enthält, benutzen Sie die Methode utf8() um ein char* zu erhalten.}}

=== ki18n ===
Die <tt>i18n()</tt> Methoden benötigt ein existierendes {{Class|KInstance}} (z.B. ein {{Class|KApplication}}) Objekt. Für Zeichenketten die vor der Erzeugung erstellt werden muss eine andere Methode zur Verfügung gestellt werden: <tt>ki18n</tt>. Diese erlaubt es, Zeichenketten zur späteren übersetzung zu markieren. ki18n() gibt ein {{Class|KLocalizedString}} zurück, welches letztlich in ein {{Qt|QString}} konvertiert wird (also schließlich übersetzt wird), nachdem KInstance erzeugt wurde. Dabei wird dessen toString() Methode benutzt.

ki18n() wird typischerweise in Zeichenketten benutzt, die an {{Class|KAboutData}} übergeben werden, da dieses von {{Class|KApplication}} erzeugt wird. Außerhalb dieser Sonderfälle kann man immer ohne Bedenken i18n() benutzen, wenn man sicher ist, dass dieser Code ausgeführt nachdem KApplication oder eine andere {{Class|KInstance}} konstruiert wurde.

=== Kontext hinzufügen ===

There is an extended version of <tt>i18n()</tt>, <tt>i18nc()</tt> which takes two <tt>const char*</tt> arguments. The first argument is an additional contextual description of the second string which will be translated. The first string is used to find the proper corresponding translation at run-time and is shown to translators to help them understand the meaning of the string.

Use <tt>i18nc()</tt> whenever the purpose of the text might be ambiguous without further context. For example, consider a context menu in a file manager with an entry called "View" which opens a viewer for the currently selected file. In this context "View" is a verb. However, the same application also may have a menu called "View" in the menubar. In that context "View" is a noun. In the English version of the application everything looks fine, but in most other languages one of the two "View" strings will be incorrect.

Additionally, translators sometimes need extra help in understanding what the text is actually referring to during the translation process.

In the file manager example above, one might therefore write:

<code cppqt>contextMenu->addAction(i18nc("verb, to view something", "View"));
viewMenu->addAction(i18nc("noun, the view", "View"));</code>

Now the two strings will be properly translatable, both by the human translators and at runtime by KLocale.

Use this form of i18n whenever the string to translate is short or the meaning is hard to discern when the context is not exactly known. For example:

<code cppqt>QString up = i18nc("Go one directory up in the hierarchy", "Up");
QString relation = i18nc("A person's name and their familial relationship to you.", "%1 is your %2", name, relationship);</code>

{{note (de)|There is also a ki18nc("context","text") method for providing context to strings which are constructed before the KInstance. It returns a KLocalizedString, so use the toString() method afterwards to convert it into a QString.}}

Contexts can also be added when building forms in Qt Designer. Each widget label, including tooltips and whatsthis texts, has a "comment" attribute, which will serve the same purpose as first argument to <tt>i18nc()</tt> call.

=== Standard Kontext für häufige Ausdrücke ===

Below is a chart showing some common words and phrases in English and the context that must be used with them to ensure proper translation of them in other languages.

{|
|+ Standard Contexts
|-
! Phrase !! Context !! i18nc Call !! Example
|-
| Busy || Refering to a person || <tt>i18nc("A person is busy", "Busy")</tt>
|-
| Busy || Refering to a thing || <tt>i18nc("A thing is busy", "Busy")</tt>
|-
| Color || Color mode, as opposed to Grayscale || <tt>i18nc("Color mode", "Color")</tt>
|-
| Creator || Refering to a person || <tt>i18nc("A person who creates", "Creator")</tt>
|-
| Creator || Refering to software || <tt>i18nc("Software", "Creator")</tt>
|-
| Display || Refering to hardware || <tt>i18nc("Hardware display", "Display")</tt>
|-
| Editor || Refering to a person || <tt>i18nc("A person who edits", "Editor")</tt>
|-
| Editor || Refering to software || <tt>i18nc("Software", "Editor")</tt>
|-
| Line || Refering to drawing || <tt>i18nc("Draw a line", "Line")</tt>
|-
| Line || Refering to text || <tt>i18nc("Line of text", "Line")</tt>
|-
| Name || Refering to a name of thing || <tt>i18nc("A thing's name", "Name") || In theme change dialog: i18nc("Theme name", "Name")</tt>
|-
| Name || Refering to first name and last name of person || <tt>i18nc("Person's first and last name", "Name") || In KAddessbook contact edit dialog: i18nc("Person's first and last name", "Name")</tt>
|-
| No || Answer to a question || <tt>i18nc("Answer to a question", "No")</tt>
|-
| No || Availability of a thing || <tt>i18nc("Availability", "No")</tt>
|-
| (Re)load || (Re)load a document, medium etc. || <tt>i18nc("(Re)load a document", "(Re)load")</tt>
|-
| (Re)load || (Re)start a program, daemon etc. || <tt>i18nc("(Re)start a program", "(Re)load")</tt>
|-
| Title || Refering to a person || <tt>i18nc("A person's title", "Title")</tt>
|-
| Title || Refering to a thing || <tt>i18nc("A thing's title", "Title")</tt>
|-
| Volume || Refering to sound || <tt>i18nc("Sound volume", "Volume")</tt>
|-
| Volume || Refering to a filesystem || <tt>i18nc("Filesystem volume", "Volume")</tt>
|-
| Volume || Refering to books || <tt>i18nc("Book volume", "Volume")</tt>
|-
| Yes || Answer to a question || <tt>i18nc("Answer to a question", "Yes")</tt>
|-
| Yes || Availability of a thing|| <tt>i18nc("Availability", "Yes")</tt>
|}

=== Plural ===

Plurals are handled differently from language to language. Many languages have different plurals for 2, 10, 20, 100, etc. When the string you want translated refers to more than one item, you must use the third form of <tt>i18n</tt>, the <tt>i18np()</tt>. It takes the singular and plural English forms as its first two arguments, followed by any substitution arguments as usual, but at least one of which should be integer-valued. For example:

<code cppqt>msgStr = i18np("1 image in album %2", "%1 images in album %2", numImages, albumName);</code>

<tt>i18np()</tt> gets expanded to as many cases as required by the user's language. In English, this is just two forms while in other languages it may be more, depending on the value of the first integer-valued argument.

Note that this form should be used even if the string always refers to more than one item as some languages use a singular form even when referring to a multiple (typically for 21, 31, etc.). This code:

<code cppqt>i18n("%1 files were deleted", numFilesDeleted);</code>

is therefore incorrect and should instead be:

<code cppqt>i18np("1 file was deleted",
"%1 files were deleted",
numFilesDeleted);</code>

To provide context as well as pluralization, use <tt>i18ncp</tt> as in this example:

<code cppqt>i18ncp("Personal file", "1 file", "%1 files", numFiles);</code>

== Datum und Zahlen formatieren ==

When displaying a number to the user, your program must take care of the decimal separator, thousand separator and currency symbol (if any) being used. These symbols differ from region to region. In English speaking countries a dot (.) is used to separate the fractional part of a number, while in some European countries a comma (,) is used instead. Below is a short summary of functions that will help you format the numbers correctly, taking the local conventions into account for you.

{|
|+ Functions to Format Numbers
|-
! Formats a.. !! From a.. !! Function Prototype
|-
| Number || String || <pre>QString formatNumber( const QString & numStr )</pre>
|-
| Number || Integer, double || <pre>formatNumber( double num,
int precision = -1 )</pre>
|-
| Money || String || <pre>formatMoney( const QString & numStr )</pre>
|-
| Money || Number || <pre>formatMoney( double num,
const QString & currency,
int digits = -1 )</pre>
|-
| Date || String || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Time || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false)</pre>
|-
| Date and time || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat = true,
bool includeSecs = false )</pre>
|}

Similar functions exist to read information provided by the user at runtime in their localized format, e.g. readNumber() or readMoney().

== Kalender ==

Applikationen zu entwickeln, die sich mit Datum und Zeit beschäftigen, zum Beispiel Kalender, ist ein sehr komplexes Gebiet. Nicht nur Zeichenketten die ein Datum oder eine Uhrzeit beinhalten müssen lokal angepasst werden, man muss auch andere Aspekte bedenken, wie zum Beispiel:
* Welcher Dag in der Woche der erste ist (cf int weekStartDay())
* Wieviele Monate in einem Jahr sind
* "Ära"-basierte Kalender
* Ob ein 24-Stunden Zeitformat benutzt wird (cf bool use12Clock())

KLocale stellt neben anderen diese Methoden zur verfügung:

{|
|+ Kalenderdaten Funktionen
|-
! Formats a.. !! From a.. !! Function Prototype
|-
| Date || QDate || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Time || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false )</pre>
|-
| Date and time || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat=true,
bool includeSecs=false )</pre>
|}

{{improve (de)|Mehr Informationen für verschiedene Kalendersysteme geben}}

== Häufige Fallen vermeiden ==
Es gibt eine Reihe von häufigen Problemen die es unmöglich machen, eine Applikation angemessen zu lokalisieren. Im nächsten Kapitel [[../i18n Mistakes (de)|Häufige Fehler in der Lokalisation vermeiden]] lernen Sie mehr darüber und wie man solche Fehler vermeidet.

{{note (de)|Dank geht an Lukáš Tinkl, Matthias Kiefer und Gary Cramblitt für die Originalversion dieser Anleitung.}}

[[Category:Programming]]

Development/Tutorials/Common Programming Mistakes (de)

2007-12-21T11:17:28Z

DrSlowDecay: /* Iteratoren */ Changed template to german version

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Common Programming Mistakes}}

{{TutorialBrowser (de)|

series=Grundlagen|

name=Häufige Programmierfehler|

}}

== Zusammenfassung ==
Diese Anleitung gibt ein paar Tips aus dem Erfahrungsschatz von KDE Entwicklern bezüglich was man in Qt und KDE machen und was lieber sein lassen sollte. Neben aktuellen Fehler behandelt es auch Dinge, die nicht unbedingt als Fehler gelten jedoch den Code langsamer oder weniger lesbar machen.

== C++ allgemein==
Dieses Kapitel beschäftigt sich mit einigen dunklen Ecken von C++, die gerne falsch benutzt oder schlicht und einfach falsch verstanden werden.

=== Anonyme Namensräume vs. statics ===
Wenn Sie eine Methode in einer Klasse haben, die nicht auf Members zugreift und daher kein Objekt zu seiner Arbeit benötigt, machen Sie es static. Wenn diese Methode dann zusätzlich nur eine private Hilfsfunktion ist, welche außerhalb dieser Datei nicht benötigt wird, machen Sie daraus eine file-static Funktion, dadurch wird das Symbol komplett verborgen.

Symbole die in C++ in einem anonymen Namensraum definiert werden, haben keine interne Verknüpfung. Anonyme Namensräume vergeben nur einen eindeutigen Namen für diese Übersetzungseinheit und das ist alles. Die Verknüpfung des Symbols wird überhaupt nicht verändert, weil die zweite Phase einer zwei-Phasen Namenssuche Funktionen mit interner Verknüfung ignoriert. Weiterhin können Elemente mit interner Verknüpfung nicht als Argumente für Templates benutzt werden.

Wenn Sie also nicht wollen, dass ein Symbol exportiert wird, benutzen Sie statt anonymen Namensräumen statische.

=== NULL Zeiger Probleme ===
Als erstes und wichtigstes: Es ist OK einen Null Zeiger zu löschen. Daher sind Konstrukte, die einen Zeiger auf Null testen reduntant:
<code cppqt>
if ( ptr ) {
delete ptr;
}
</code>

Beachten Sie jedoch, dass '''ein Null-Check erforderlich ''ist'', wenn Sie ein Array löschen''' - das liegt daran, dass ein relativ neuer Compiler auf Solaris-Systemen das anderweitig nicht richtig behandelt.

Wenn Sie einen Zeiger löschen, stellen Sie sicher, dass sie ihn auf 0 setzen, so dass zukünftige Löschversuche nicht mit einer doppelten Löschung fehlschlagen. Der entsprechende Code dazu:

<code cppqt>
delete ptr;
ptr = 0;
</code>

Ihnen mag aufgefallen sein, dass Null-Zeiger auf eine von drei Arten bezeichnet werden können: 0, 0L und NULL. In C ist NULL als null void Zeiger definiert. In C++ ist dies jedoch nicht möglich aufgrund einer strengeren Typprüfung. Daher definieren moderne C++ Implementationen eine "magische" Null-Zeiger Konstante, die einem beliebigen Zeiger zugewiesen werden kann. Ältere C++ Implementationen definierten es einfach als 0L oder 0, was keine zusätzliche Typsicherheit bietet - man könnte es einer Integervariable zuweisen, was offensichtlich falsch ist.

Bei Zeigern bedeutet die Integerkonstante Null "Null-Zeiger" - unabhängig von der aktuellen Binärdarstellung eines Null-Zeigers. Daher ist die Entscheidung zwischen 0, 0L und NULL eine Frage des persönlichen Stils und der Gewohnheit statt technischer Gegebenheiten - was den Code in KDE's SVN betrifft, werden Sie mehr 0 als NULL verwendet sehen.

Beachten Sie jedoch, das wenn Sie eine Null-Zeiger Konstante an eine Funktion mit variabler Parameterliste übergeben, Sie diese explizit in eine Zeiger-Variable ändern müssen - der Compiler nimmt per Voreinstellung den Integerkontext an, was möglicherweise nicht der Binärdarstellung eines Null-Zeigers entspricht. Wieder ist es egal, ob Sie 0, 0L oder NULL verwenden, im Allgemeinen wird die kürzere Darstellung bevorzugt.

=== Member Variablen ===
Sie werden vielleicht vier Hauptstile bemerkt haben, wie in KDE-Klassen Member-Variablen benannt werden:

* '''m_variable''' kleines m, Unterstrich und der Name der Variable mit einem Kleinbuchstaben am Anfang. Das ist der am meisten verwendete Stil und wird im Code von kdelibs bevorzugt.
* '''mVariable''' kleines m und der Name der Variable mit einem Großbuchstaben am Anfang
* '''variable_''' Name der Variable mit einem Kleinbuchstaben am Anfang und variable einem Unterstrich am Ende
* '''_variable''' Unterstrich und der Name der Variable mit einem Kleinbuchstaben am Anfang. Dieser Stil wird nicht so gerne gesehen, da diese Notation auch in Code für Funktionsparameter verwendet wird.

Wie immer gibt es nicht nur einen korrekten Weg es zu machen, so folgen Sie einfach der Syntax der Applikation/Bibliothek zu welcher Sie Code ergänzen.

=== Static variablen ===

Versuchen Sie die Anzahl der static Variablen in Ihrem Code zu limitieren, besonders wenn Sie an einer Bibliothek arbeiten. Konstruktion und Initialisierung einer großen Anzahl von static Variablen kann die Startzeit stark verlängern.

Benutzen Sie keine class-static Variablen, besonders nicht in Bibliotheken und ladbaren Modulen obwohl es sogar in Applikationen nicht empfohlen wird. Static Objekte führen zu einer Menge Problemen wie schwer zu verolgende Abstürze wegen einer undefinierten Reihenfolge des Konstruktion/Destruktion.

Benutzen Sie stattdessen einen static Zeiger, zusammen mit <tt>K_GLOBAL_STATIC</tt> welches in <tt>kglobal.h</tt> definiert wird und wie folgt benutzt wird:
<code cppqt>
class A { ... };

K_GLOBAL_STATIC(A, globalA)

void doSomething()
{
A *a = globalA;
...
}

void doSomethingElse()
{
if (globalA.isDestroyed()) {
return;
}
A *a = globalA;
...
}

void installPostRoutine()
{
qAddPostRoutine(globalA.destroy);
}
</code>

Sehen Sie auch [http://www.englishbreakfastnetwork.org/apidocs/apidox-kde-4.0/kdelibs-apidocs/kdecore/html/kglobal_8h.html#75ca0c60b03dc5e4f9427263bf4043c7 API Dokumentation] für <tt>K_GLOBAL_STATIC</tt>, um weitere Informationen zu erhalten.

=== Forward Deklarationen ===

Die Übersetzungszeit kann reduziert werden, indem man Klassen ''forward'' deklariert anstatt den entsprechenden Header einzubinden. Ein Beispiel:

<code cppqt>
#include <QWidget> // langsam
#include <QStringList> // langsam
#include <QString> // langsam
class SomeInterface
{
public:
virtual void widgetAction( QWidget *widget ) =0;
virtual void stringAction( const QString& str ) =0;
virtual void stringListAction( const QStringList& strList ) =0;
};
</code>

Das obige sollte statt dessen folgendermaßen formuliert werden:

<code cppqt>
class QWidget; // schnell
class QStringList; // schnell
class QString; // schnell
class SomeInterface
{
public:
virtual void widgetAction( QWidget *widget ) =0;
virtual void stringAction( const QString& str ) =0;
virtual void stringListAction( const QStringList& strList ) =0;
};
</code>

=== Iteratoren ===
Bevorzugen Sie <tt>const_iterators</tt> vor normalen Iterationen wann immer es möglich ist.

{{improve (de)|Einige Abschnitte in diesem Kapitel konnte ich leider nicht übersetzen.}}

Containers, which are being implicitly shared often detach when a call to a non-const <tt>begin()</tt> or <tt>end()</tt> methods is made ({{qt|List}} ist ein Beispiel eines solchen Containers).

Wenn Sie einen const_iterator benutzen, achten Sie auch darauf, wirklich die const-Version von <tt>begin()</tt> und <tt>end()</tt> aufzurufen.

Unless your container is actually const itself this probably will not be the case, possibly causing an unnecessary detach of your container. So basically whenever you use const_iterator initialize them using <tt>constBegin()</tt>/<tt>constEnd()</tt> instead, to be on the safe side.

Speichern Sie den Rückgabewert des <tt>end()</tt> Methodenaufrufs zwischen bevor Sie eine Iteration in großen Containern ausführen. Zum Beispiel:

<code cppqt>
QValueList<SomeClass> container;

//Code, der eine große Anzahl von Elementen in den Container einfügt.

QValueListConstIterator end( container.end() );

for ( QValueListConstIterator itr( container.begin() );
itr != end; ++itr ) {
}
</code>

Dadruch wird die unnötige Erzeugung eines temporären Rückgabe Objektes für <tt>end()</tt> in jedem Schleifendurchlauf vermieden und dadurch die Ausführung beschleunigt.

Prefer to use pre-increment over post-increment operators on iterators as this avoids creating an unnecessary temporary object in the process.

'''Seien Sie vorsichtig wenn Sie Elemente innerhalb einer Schleife löschen'''

Wenn Sie einige Elemente aus der Liste löschen wollen, könnten Sie vielleicht einen Code wie folgenden benutzen wollen:

<code cppqt>
QMap<int, Job *>::iterator it = m_activeTimers.begin();
QMap<int, Job *>::iterator itEnd = m_activeTimers.end();

for( ; it!=itEnd ; ++it )
{
if(it.value() == job)
{
//A timer for this job has been found. Let's stop it.
killTimer(it.key());
m_activeTimers.erase(it);
}
}
</code>
Dieser Code wird eventuell wegen eines hängenden Iterators nach dem Aufruf von erase() einen Crash erzeugen.
Sie müssen den Code folgendermaßen umschreiben:
<code cppqt>
QMap<int, Job *>::iterator it = m_activeTimers.begin();
while (it != m_activeTimers.end())
{
QMap<int, Job *>::iterator prev = it;
++it;
if(prev.value() == job)
{
//A timer for this job has been found. Let's stop it.
killTimer(prev.key());
m_activeTimers.erase(prev);
}
}
</code>
Dieses Problem wird auch in [http://doc.trolltech.com/4.3/qmap-iterator.html#details Qt documentation for QMap::iterator] diskutiert, trifft aber auf alle Qt Iteratoren zu.

== Programm Design ==
In diesem Abschnitt beschäftigen wir uns mit einigen allgemeinen Problemen im Zusammenhang mit den Design von Qt/KDE Applikationen.

=== Verspätete Initialisierung ===
Obwohl das Design von modernen C++ Applikationen sehr komplex sein kann, ist ein immer wieder auftretendes Problem - was jedoch leicht zu beheben ist - die Tatsache nicht die Technik der [http://www.kdedevelopers.org/node/view/509 verspäteten Initialisierung] zu benutzen.

Zunächst sehen wir uns den Standardweg einer Initialisierung einer KDE Applikation an:

<code cppqt>
int main( int argc, char **argv )
{
....
KApplication a;

KCmdLineArgs *args = KCmdLineArgs::parsedArgs();

MainWindow *window = new MainWindow( args );

a.setMainWidget( window );
window->show();

return a.exec();
}
</code>
Beachten Sie, dass <tt>window</tt> vor dem Aufruf von <tt>a.exec()</tt>, der die Ereignisschleife startet, erzeugt wird. Das bedeutet, dass wir es vermeiden sollten, nicht-triviales im obersten Konstruktor durchzuführen, da dieser Läuft bevor das Fenster überhaupt dargestellt werden kann.

Die Lösung ist einfach: Wir müssen die Konsruktion von Dingen außer der GUI solange verzögern, bis die Ereignisschleife startet. Hier ist ein Beispiel, wie der Konstruktor eines MainWindows aussehen sollte, um das zu erreichen:

<code cppqt>
MainWindow::MainWindow()
{
initGUI();
QTimer::singleShot( 0, this, SLOT(initObject()) );
}

void MainWindow::initGUI()
{
/* Erzeugen Sie Ihre Widgets hier. Beachten Sie das die Widgets
* die Sie hier erzeugen, keine komplexe Initialisierung beötigen sollten
* da ansonsten die Ganze Aktion nicht viel Sinn macht. Alles was
* hier geschehen sollte, ist die Erzeugung der GUI Objekte und das
* Verknüfen via QObject::connect der entsprechenden Signals mit deren
* Slots
*/
}

void MainWindow::initObject()
{
/* Dieser Slot wird aufgrufen sobald die Ereignisschleife startet.
* Implementieren Sie hier alles was sonst noch getan werden muss,
* inklusive dem Wiederherstellen von Werten, dem Lesen von Dateien,
* Wiederherstellung von Sitzungen, etc.
* Das wird immer noch eine Zeit dauern, aber wenigstens ist Ihr
* Fenster in dieser Zeit sichtbar und so macht die Applikation
* einen aktiven Eindruck.
*/
}
</code>

Diese Technik gibt ihnen keinen Zeitvorteil (es läuft nichts schneller dadurch), aber die Applikation macht für den Benutzer den Eindruck, als würde sie schneller starten. Das wird dadurch bewerkstelligt, dass der Benutzer eine schnelle Antwort auf das starten der Applikation erhält.

Wenn (und nur dann) der Start nicht in einem vernünftigen Zeitrahmen erfolgen kann, überlegen Sie sich, ein {{class|KSplashScreen}} einzusetzen.

== Daten Strukturen ==

In this section we will go over some of our most common pet-peeves which affect data structures very commonly seen in Qt/KDE applications.

=== non-POD typen übergeben ===

Nicht-POD ("plain old data") Typen sollten als const Referenz übergeben werden, wann immer das möglich ist. Das beinhaltet alle Datentypen außer <tt>char</tt> und <tt>int</tt>.

Nehemen Sie zum Beispiel {{qt|QString}}. Diese sollten als Parameter an Methoden immer als <tt>const {{qt|QString}}&</tt> übergeben werden. Auch wenn {{qt|QString}} implicitly shared ist, ist das immer noch effizienter (und sicherer) es als const Referenz zu übergeben statt als Wert.

So allgemein sollte eine Methode, die QString als Argument nimmt, so aussehen:

<code cppqt>
void myMethod( const QString & foo, const QString & bar );
</code>

=== QObject ===
Sollten Sie jemals eine von QObject abgeleitete Klasse aus den eigenen Methoden heraus löschen sollen, löschen Sie es ''nicht'' folgendermaßen:
<code cppqt>
delete this;
</code>

Das wird früher oder später in einen Absturz führen, da eine Methode dieses Objektes aus der Qt-Ereignisschleife heraus via slots/signals aufgerufen werden könnte, nachdem Sie es gelöscht haben.

Nutzen Sie statt dessen immer <tt>{{qt|QObject}}::deleteLater()</tt>, was das gleiche wie <tt>delete this</tt> erledigt jedoch in einer sicheren Art und Weise.

=== Leere QStrings ===
Häufig muss geprüft werden, ob ein {{qt|QString}} leer ist. Hier sind drei Ansätze das zu prüfen, wobei nur die ersten beiden korrekt sind:

<code cppqt>
// Richtig
if ( mystring.isEmpty() ) {
}

// Richtig
if ( mystring == QString() ) {
}

// Falsch! ""
if ( mystring == "" ) {
}
</code>

Obwohl es ein Unterschied zwischen "null" {{qt|QString}}s und leeren gibt, ist das nur ein historisches Artefakt, neuer Code sollte das nicht mehr benutzen.

=== QString und das Lesen aus Dateien ===
Wenn Sie aus einer Datei lesen, ist es schneller, in einem Rutsch von der lokalen Verschlüsselung nach Unicode ({{qt|QString}}) zu konvertieren als zeilenweise. Das bedeutet, dass Methoden wie <tt>{{qt|QIODevice}}::readAll()</tt> meist eine gute Lösung sind, gefolgt von einer einizigen {{qt|QString}} instantierung.

Bei größeren Dateien sollte sich in Betracht ziehen, einen Block von Zeilen zu lesen und dann zu konvertieren. Auf diese Art und Weise haben Sie die Möglichkeit ihre GUI zu aktualisieren. Das kann bewekstelligt werden, indem Sie wieder in die Ereignisschleife eintreten und gleichteitig mittels eines Timers die Blöcke im Hintergrund lesen oder indem Sie eine lokale Ereignisschleife definieren.

Man könnte auch <tt>qApp->processEvents()</tt> aufrufen, davon wird jedoch abgetraten, da es leicht zu zum Teil fatalen Problemen führt.

=== QString aus einem KProcess lesen ===
{{class|KProcess}} löst das Signal <tt>readyReadStandard{Output|Error}</tt> aus, sobald Daten eintreffen.

Ein häufiger Fehler ist es, alle verfügbaren Daten im verbundenen Slot zu lesen und sofort in ein {{qt|QString}} zu konvertieren: Die Daten könnten in kleineren unregelmäßigen Portionen einreffen, daher könnten multi-byte Zeichen in Stücke geschnitten und daher ungültig werden. Mehrere Ansätze existieren:

<ul>
<li>Müssen Sie die Daten wirklich sofort verarbeiten sobald sie eintreffen? Wenn nicht, benutzen Sie lieber <tt>readAllStandard{Output|Error}</tt> nachdem der Prozess beendet wurde. Anders als in KDE3 ist KProcess nun in der Lage, die Daten zu sammeln.</li>
<li>Sammeln Sie die Datenbrocken im Slot und bearbeiten Sie sie immer dann, wenn ein Newline kommt oder ein bestimmter Timeout auftritt.[http://websvn.kde.org/branches/KDE/3.5/kdevelop/lib/widgets/processlinemaker.cpp?view=markup&rev=737977 Example code] (KDE3 based)</li>
<li>Fügen Sie den Prozess in ein {{qt|QTextStream}} ein und lesen Sie diesen zeilenweise. Während das zumindest theoretisch funktionieren sollte, funktioniert das in der Praxis derzeit '''nicht'''.</li>
</ul>

=== QString und QByteArray ===
Während {{qt|QString}} das Werkzeug der Wahl für viele Situationen ist, in denen mit Zeichenketten gearbeitet wird, gibt es eine Situation, wo dies äußerst ineffizient ist. Wenn Sie mit Daten arbeitet, die in einem {{qt|QByteArray}} gespeichert sind, sehen Sie sich vor, dass Sie diese nicht an Methoden übergeben, die einen {{qt|QString}} Parameter benötigen und daraus wieder ein QByteArray macht.

For example:

<code cppqt>
QByteArray myData;
QString myNewData = mangleData( myData );

QString mangleData( const QString& data ) {
QByteArray str = data.toLatin1();
// mangle
return QString(str);
}
</code>

Der kostspielige Teil hier ist die Konvertierung nach {{qt|QString}}, was intern als Konvertierung in Unicode durchgeführt wird. Das ist unnötig, da das erste, was die Methode tut, eine Rückkonvertierung nach <tt>toLatin1()</tt> ist. Wenn Sie sich also sicher sind, dass eine Unicode Konvertierung nicht bennötigt wird, versuchen sich Zwischenschritte mit QString zu vermeiden.

Das obige Beispiel sollte statt dessen geschrieben werden als:

<code cppqt>
QByteArray myData;
QByteArray myNewData = mangleData( myData );

QByteArray mangleData( const QByteArray& data )
</code>

=== QDomElement ===
When ein XML Dokument geparst wird, benötigt man häufig eine Iteration über alle Elemente. Man könnte versucht sein, folgenden Code dafür zu benutzen:

<code cppqt>
for ( QDomElement e = baseElement.firstChild().toElement();
!e.isNull();
e = e.nextSibling().toElement() ) {
...
}
</code>

Das ist jedoch nicht korrekt: Die obige Schleife wird vorzeitig beendet wenn es auf einen {{qt|QDomNode}} trifft, der etwas anderes als ein Element ist (zum Beispiel ein Kommentar).

Die korrekte Schleife sieht so aus:

<code cppqt>
for ( QDomNode n = baseElement.firstChild(); !n.isNull();
n = n.nextSibling() ) {
QDomElement e = n.toElement();
if ( e.isNull() ) {
continue;
}
...
}
</code>

Development/Tutorials/KDE4 Porting Guide (de)

2007-12-21T11:16:13Z

DrSlowDecay: /* Qt Designer UI Dateien */ Adjusted template to german version

{{Template:I18n/Language Navigation Bar|Development/Tutorials/KDE4_Porting_Guide}}

{{TutorialBrowser (de)|

series=Grundlagen|

name=Anleitung zur Portierung nach KDE 4|

pre=|

next=[[Development/Tutorials/CMake (de)|Einführung in CMake]]|

reading=[http://www.trolltech.com/products/qt/whatsnew/porting "Moving from Qt 3 to Qt 4"]
}}

==Einführung==
Diese Anleitung richtet sich an Entwickler, die ihre Qt3/KDE3 basierten Applikationen nach Qt4/KDE4 portieren wollen. Das muß nämlich kein komplizierter Prozess sein. Es gibt bereits viele Skripte und Dokumentationen, die dabei helfen.

==Konventionen==
Für die Anweisungen dieser Anleitung gelten folgende Konventionen:
* {{program|program}} bezeichnet ein ausführbares Programm
* {{path|path}} bezeichnet einen Pfad
* {{path|file}} bezeichnet eine Datei
* $SVN ist der vollständige Pfad zu Ihrem KDE subversion depot.

==CMake==
Anders als KDE4 werden KDE4 Applikationen mit der Hilfe von [[Development/Tutorials/CMake (de)| CMake]] erstellt. Der einfachste Weg die autotools Dateien nach CMake zu portieren ist, das Script {{program|am2cmake}} zu benutzen, welches im Verzeichnis {{path|cmake/scripts}} des [http://websvn.kde.org/trunk/KDE/kdesdk/ kdesdk] Modules zu finden ist. Das erzeugt eine Reihe von {{path|CMakeLists.txt}} Dateien neben den alten autotools Dateien.

Ist Ihr Code zum Beispiel unter {{path|/path/to/src}} gespeichert, dann:
<code bash>
% cd /path/to/src
% $SVN/trunk/KDE/kdesdk/cmake/scripts/am2cmake --kde4
</code>
Führen Sie <tt>am2cmake --help</tt> aus, um zu prüfen, ob Sie das <tt>--kde4</tt> Flag benötigen.

Weiterhin gibt es ein Werkzeug, welches in den erzeugten {{path|CMakeList.txt}} Dateien nach möglichen Problemen sucht. Dieses Werkzeugt heißt {{program|cmakelint.pl}} und ist unter{{path|$SVN/trunk/kde/kdesdk/scripts}} gespeichert. Benutzen Sie es folgendermaßen:
<code bash>
% cd /path/to/src
% $SVN/trunk/KDE/kdesdk/scripts/cmakelint.pl CMakeLists.txt
</code>
Oder wenden Sie es auf das gesamte Quellcodevrzeichnis an:
<code bash>
% cd /path/to/src
% find . -name CMakeLists.txt | \
xargs $SVN/trunk/KDE/kdesdk/scripts/cmakelint.pl
</code>

==Qt4 API==
Einen Überblick über den Übergang von Qt3 nach Qt4 wird in der Anleitung [http://www.trolltech.com/products/qt/whatsnew/porting "Moving from Qt 3 to Qt 4"] von Trolltech erläutert. Dieses Dokument bietet einen sehr guter Überblick über die Änderungen in der Funktionalität, die Qt4 mit sich bring und ist daher sehr zu empfehlen.

Die nachfolgende Anleitung [http://doc.trolltech.com/latest/porting4.html "Porting to Qt 4"] gibt eine sehr detailierte Beschreibung des Portierungsprozesses, neben einer Liste von Änderungen in den Klassen und Funktionen.

Diese Dokumente beschreiben auch ein Werkzeug, das von Trolltech zur Verfügung gestellt wird und sich {{program|qt3to4}} nennt. Dieses Programm kann dabei helfen, die Qt Teile Ihres Codes von Qt3 nach Qt4 zu portieren, indem es spezielle Funktionen zur Kompatibilität benutzt. Rufen Sie {{program|qt3to4}} folgendermaßen auf:
<code bash>
% $SVN/trunk/qt-copy/bin/qt3to4 [options] <Infile>, [Infile], ...
</code>
Infile kann eine Quellcodedatei oder eine Projektdatei sein. Möchten Sie eine Projektdatei angeben (mit der Endung '.pro' oder '.pri'), {{program|qt3to4}} wird alle Dateien portieren, die in dieser Datei angegeben sind.

Für mehr Informationen können Sie {{program|qt3to4}} mit der "--help" Option aufrufen oder unter [http://doc.trolltech.com/latest/qt3to4.html "qt3to4-The Qt 3 to 4 Porting Tool"] nachschlagen.

Weiterhin gibt es ein Programm namens {{program|remove-qt3-support.pl}} im Modul {{module|kdesdk}}, welches nach vielen veralteten Qt3 Strukturen sucht und diese ersetzt. Rufen Sie einfach dieses Programm ohne weitere Optionen im Quellverzeichnis auf.
<code bash>
% $SVN/trunk/KDE/kdesdk/scripts/qt4/remove-qt3-support.pl
</code>

==KDE4 API==
Ein Großteil der Arbeit beim Portieren besteht einfach aus dem umbenennen von Klassen und Header-Dateien. Da es ziemlich ermüdend ist, dies von Hand zu machen, gibt es ein nützliches Script im {{path|scripts/qt4}} Verzeichnis des Modules {{module|kdesdk}} namens {{program|adapt-to-kde4-api.pl}}. Dieses scant alle Ihre Dateien und erzeugt eine {{program|diff}} Ausgabe, die dann benutzt werden kann, um Ihren Code zu patchen.

Wenn diese einfache Codeersetzung erledigt ist, müssen Sie trotzdem noch Ihren zu portierenden Code nachbearbeiten, zum Beispiel wegen der neuen <tt>KAction</tt> API. Über alle API Änderungen informiert Sie die Datei [http://websvn.kde.org/*checkout*/trunk/KDE/kdelibs/KDE4PORTING.html KDE4PORTING.html] des Modules {{module|kdelibs}}.

==Qt Designer UI Dateien==
Die ".ui" Dateien, die vom Qt Designer unter Qt3 produziert wurden müssen in das neue Qt4 Format konvertiert werden. Dazu kann man das Programm {{program|uic3}} benutze, welches in Ihrer Qt4 Installation zur Verfügung gestellt wird.

<code bash>
% $SVN/trunk/qt-copy/bin/uic3 -convert file.ui > foo.ui
% mv foo.ui file.ui
</code>

Oder, wenn Sie ein graphisches Werkzeug vorziehen, können Sie auch das Designer Programm von Qt4 benutzen

<code bash>
% $SVN/trunk/qt-copy/bin/designer file.ui
(you can save file.ui over top itself, or save to a new file)
</code>
{{Warning (de)|Beachten Sie, dass durch den Konvertierungsprozess einige selbstdefinierten Slots, Tabellen Spalten, etc verloren gehen können. Es kann also sein, dass Sie diese Dinge dann von Hand wiederherstellen müssen.}}

Sie sollten auch das Programm {{program|fixuifiles}} aus dem Modul {{module|kdesdk}} ausführen, welches einige Säuberungen und Plausibilitätsprüfungen durchführt.
<code bash>
% $SVN/trunk/KDE/kdesdk/scripts/fixuifiles
</code>

==D-Bus==
Statt DCOP, wie es in KDE3 benutzt wird, kommt in KDE4 nun D-Bus für die Kommunikation zwischen Prozessen (interprocess communication) zum Einsatz. Die Portierung von DCOP nach D-BUS ist ein großes Thema, welches im Detail in der Anleitung [[Development/Tutorials/Porting_to_D-Bus|Porting to D-Bus]] (in englisch) beschrieben wird.

Für mehr Informationen sehen Sie bitte auch [[Development/Tutorials#D-Bus|D-Bus tutorials]].

==Icons==
KDE4 richtet sich nach dem Namensschema für Icons, welches unter [http://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html freedesktop.org icon naming specification] (englisch) spezifiziert wird. Das bedeutet, dass sowohl Icons die mit KDE4 (Oxygen) ausgeliefert werden, als auch Komponenten in kdelibs, die Icons benutzen diesem Schema folgen.

Um Ihre Applikation von den Iconnamen, die in KDE3 benutzt wurden, in diejenigen, die jetzt in KDE4 benutzt werden zu konvertieren, rufen Sie einfach das [http://websvn.kde.org/*checkout*/trunk/KDE/kdesdk/scripts/qt4/adapt-to-icon-spec.py adapt-to-icon-spec.py] Skript aus dem Wurzelverzeichnis Ihres Projekts auf und folgen Sie den Anweisungen auf dem Bildschirm.

Das Skript konvertiert automatisch alle Icons, die sicher eine überprüfbare Entsprechung haben (z.B. die Benutzung von KIcon oder KIconLoader), überspringt diejenigen die überprüfbar keine Entsprechung haben und fragt bei den fraglich positiven Fällen nach. Letzteres geschieht mit zusätzlichen Kontextinformationen (wenn das gewünscht ist) und so muß man nur 'y' oder 'n' drücken, um die möglichen Treffer zu bestätigen oder abzulehenen und den Portierungsvorgang abzuschließen.

==Internationalization==
Um Ihre ".pot" Datei zu erzeugen, kopieren Sie die Kommandos aus der 'messages' Regel der {{path|Makefile.am}} Datei Ihres Projektes in ein Shell-Skript namens {{path|Messages.sh}}. Sie dürfen hier die gleichen Variablen ($PREPARETIPS, $XGETTEXT, $podir, etc.) als existent voraussetzen, doch beachten Sie, dass Makefiles und Shell-Skripten eine unterschiedliche Syntax haben.

Seien Sie auch vorsichtig, wenn Sie den -k Parameter mit $XGETTTEXT benutzen. Dann müssen Sie explizit alle Varianten auflisten, die Sie benutzen.

So wird zum Beispiel aus der 'messages' Erzeugungsregel:
<code>
messages: rc.cpp
rm -f tips.cpp
$(PREPARETIPS) > tips.cpp
$(XGETTEXT) -ktranslate *.cpp *.h -o $(podir)/kmail.pot
rm -f tips.cpp
</code>
folgendes {{path|Messages.sh}} Skript:
<code bash>
#! /usr/bin/env bash
$PREPARETIPS > tips.cpp
$XGETTEXT -ktranslate:1,1t -ktranslate:1c,2,2t *.cpp *.h -o $podir/kmail.pot
rm -f tips.cpp
</code>

==Do's und Don'ts==
* Benutzen Sie nicht die alten Socket-Klassen
* Benutzen Sie nicht {{qt3|QPtrList}}, und allgemein, setAutoDelete()
* Benutzen Sie keine Rasteroperationen.
* Kodieren Sie keine Darstellungsaufgaben außerhalb des paint events.
* Vermeiden Sie die Benutzung von {{qt3|QHBox}}, {{qt3|QVBox}}, {{qt3|QGrid}}. Bevorzugen Sie lieber Layouts.
* Spielen Sie nicht mit Rahmen von Groupboxes, Labels oder Lineedits um ein anderes Widget zu imitieren. Benutzen Sie lieber das passende Widget. Anstatt ein Label so zu ändern, dass es einen eingesunkenen Lineedit-Rand hat, lieber ein nur-lesen {{class|KLineEdit}} benutzen. Und statt {{class|KLineEdit}} ohne Rahmen für Widgets mit Kopierfunktion lieber {{class|KActiveLabel}} benutzen.
* Benutzen Sie keine Groupbox ohne Rahmen um Widgets zu gruppieren. Statt dessen einfach ein Layout benutzen.

==Mehr Informationen==
===Dokumentation===
* [http://doc.trolltech.com/4.3 Qt4.3 Reference]
* [http://developer.kde.org/documentation/library/svn-api.php KDE4 API Reference]
* [http://www.cmake.org/HTML/Documentation.html CMake Cross Platform Make]
* [http://websvn.kde.org/*checkout*/trunk/KDE/kdelibs/KDE4PORTING.html KDE4PORTING.html]

===Weitere Hilfe===
* #kde4-devel on irc.freenode.net

[[Category:KDE4]]

Development/Tutorials/Using KActions (de)

2007-12-21T11:15:10Z

DrSlowDecay: /* XmlGui */ Adjusted template to german version

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KActions}}

{{TutorialBrowser (de)|

series=Anleitungen für Anfänger|

name=KActions benutzen|

pre=[[Development/Tutorials/Using_KXmlGuiWindow (de)|Anleitung 2 - KXmlGuiWindow]]|

next=Todo|

reading=none
}}

==Zusammenfassung==
In diesem Kapitel wird das Konzept der Aktionen eingeführt. Aktionen sind ein vereinheitlichter Weg, dem Benutzer eine Interaktion mit Ihrem Programm zu ermöglichen

Soll zum Beispiel durch das Klicken eines Buttons, einem Eintrag im Dateimenü oder einem Tastaturshortcut das Textfeld geleert werden, wird dies alles durch eine {{class|KAction}} bewerkstelligt.

[[image:introtokdetutorial3.png|frame|center]]

==KAction==
Eine {{class|KAction}} ist ein Objekt, welches alle Informationen über das Icon und Shortcuts enthält, welche mit einer bestimmten Aktion assoziiert sind. Diese Aktion läßt sich mit einem[http://doc.trolltech.com/latest/signalsandslots.html slot] verbinden, welcher dann bestimmte Arbeiten ausführt, die bei dieser Aktion vorgesehen sind.

===Eine eigene Aktion erzeugen===
Um eine Aktion zu erzeugen, muss <tt>#include <KAction></tt> in die <tt>.cpp</tt> Datei eingefügt werden.

=====Das Objekt erzeugen=====
Wir werden hier eine Aktion erzeugen, welche die Applikation aus Kapitel 2 dahingehend erweitert, dass durch sie das Textfeld geleert wird. Die KAction wird in einer Reihe einzelner Schritte zusammengestellt. Zunächst wird das Objekt selber erzeugt:
<code cppqt>KAction* clearAction = new KAction(this);</code>
Das erzeugt ein KAction-Objekt welches <tt>clearAction</tt> heißt.

=====Text=====
Bei dem jetzt erzeugten KAction Objekt können jetzt die Eigenschaften gesetzt werden. Zunächst setzen wir einen Text der im Menü und unter seinem Icon in der Werkzeugleiste angezeigt wird:
<code cppqt>clearAction->setText(i18n("Clear"));</code>
Wie man sieht, muss dieser Text durch die <tt>i18n()</tt> Funktion geleitet werden, wenn man das Benutzerinterface später übersetzen möchte.

=====Icon=====
Soll in der Werkzeugleiste die Aktion angezeigt werden, muss man ein Icon verknüpfen, welches die Aktion bildlich beschreibt. Um das zu bewekstelligen, benutzen wir die <tt>setIcon()</tt> Funktion:
<code cppqt>clearAction->setIcon(KIcon("document-new"));</code>
Hier wird das Standardicon <tt>document-new</tt> von KDE benutzt.

=====Shortcut=====
Wir können auch einen Tastaturshortcut definieren, welcher die Aktion ausführt.. Das wird ganz einfach durch <code cppqt>clearAction->setShortcut(Qt::CTRL+Qt::Key_W);</code> bewekstelligt. In diesem Fall wird Ctrl+W mit der Aktion verknüpft.

=====Zur Sammlung hinzufügen=====
Damit das XmlGui Framework auf unsere Aktion zugreifen kann, muss diese in die ''action collection'' (Sammlung der Aktionen) der Applikation eingefügt werden. Auf diese wird über die <tt>actionCollection()</tt> Funktion zugegriffen:
<code cppqt>
actionCollection()->addAction("clear", clearAction);
</code>
Dieser Code fügt die <tt>clearAction</tt> KAction in die Sammlung ein und gibt ihr den Namen ''clear''. Dieser Name wird vom XmlGui Framework benutzt.

=====Die Aktion verbinden=====
Jetzt ist unsere Aktion vollständig aufgesetzt und sie muss nun noch verknüpft werden, damit sie etwas sinnvolles macht. Wir werden unsere Aktion mit dem <tt>clear()</tt> Slot, der zu einem KTextArea Objekt gehört, verknüpfen:
<code cppqt>
connect( clearAction, SIGNAL( triggered(bool) ),
textArea, SLOT( clear() ) );
</code>
Das gleiche würden wir in Qt mit einer {{qt|QAction}} machen

===KStandardAction===

Manche Aktionen, wie zum Beispiel 'beenden', 'speichern' und 'laden', benötigt fast jede KDE Applikation. Daher gibt es zur Vereinfachung vorgefertigte KActions, auf welche über {{class|KStandardAction}} zugegriffen wird.

Diese sind sehr einfach zu benutzen. Sobald man <tt>#include <KStandardAction></tt> im Quellcode eingefügt hat, muss man nur noch festlegen, welche Funktion bei Auslösung aufgerufen werden soll und zu welcher <tt>KActionCollection</tt> die Aktion hinzugefügt werden soll. Beispiel:

<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
Dieser Code erzeugt ein KAction Objekt mit dem entsprechenden Icon, Text und Shortcut und fügt dieses sogar zum Datei-Menü hinzu.

==Der Code==
===mainwindow.h===
<code cppqt n>
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <KXmlGuiWindow>
#include <KTextEdit>

class MainWindow : public KXmlGuiWindow
{
public:
MainWindow(QWidget *parent=0);

private:
KTextEdit* textArea;
void setupActions();
};

#endif
</code>

===mainwindow.cpp===
<code cppqt n>
#include "mainwindow.h"

#include <KApplication>
#include <KAction>
#include <KLocale>
#include <KActionCollection>
#include <KStandardAction>

MainWindow::MainWindow(QWidget *parent)
: KXmlGuiWindow(parent)
{
textArea = new KTextEdit;
setCentralWidget(textArea);

setupActions();
}

void MainWindow::setupActions()
{
KAction* clearAction = new KAction(this);
clearAction->setText(i18n("Clear"));
clearAction->setIcon(KIcon("document-new"));
clearAction->setShortcut(Qt::CTRL+Qt::Key_W);
actionCollection()->addAction("clear", clearAction);
connect(clearAction, SIGNAL(triggered(bool)),
textArea, SLOT(clear()));

KStandardAction::quit(kapp, SLOT(quit()),
actionCollection());

setupGUI();
}
</code>

===main.cpp===
<code cppqt n>
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>

#include "mainwindow.h"

int main (int argc, char *argv[])
{
KAboutData aboutData( "tutorial3", "tutorial3",
ki18n("Tutorial 3"), "1.0",
ki18n("A simple text area using KAction etc."),
KAboutData::License_GPL,
ki18n("Copyright (c) 2007 Developer") );
KCmdLineArgs::init( argc, argv, &aboutData );
KApplication app;

MainWindow* window = new MainWindow();
window->show();
return app.exec();
}
</code>

==Die Aktionen mit den Menüs und Werkzeugleisten verknüpfen==
Zur Zeit haben wir nur unsere neue "Clear" Aktion erzeugt. Zum jetzigen Zeitpunkt würde diese weder in den Menüs noch in den Werkzeugleisten erscheinen. Um der Applikation mitzuteilen wo die Aktion eingefügt werden soll (und dem Benutzer zu ermöglichen, diese dann beliebig umherzuschieben) wird die KDE-Technik namens XmlGui genutzt.

===XmlGui===
{{note (de)|In einer späteren Version von KDE4 könnte XmlGui durch ein neues Framework namens liveui ersetzt werden. Doch zum jetzigen Zeitpunkt ist XmlGui die einzige und korrekte Art, das UI aufzusetzen.}}

Ruft man <tt>setupGUI()</tt> in der {{class|KXmlGuiWindow}} Klasse auf, wird das XmlGui System aufgerufen, welche eine XML Datei einliest, welche das entsprechende interface beschreibt und die Buttons und Menüeinträge entsprechend erzeugt. Diese Datei wird im nächsten Schritt für unsere Applikation erzeugt.

Natürlich muss das XmlGui System wissen, welche Beschreibungs-Datei zu der jeweiligen Applikation gehört. Es muss also dem Namen und den Pfad dieser Datei kennen. Standardmäßig soll die Datei <tt>appnameui.rc</tt> genannt werden(<tt>appname</tt> ist dabei der Name, der in {{class|KAboutData}}) gesetzt wurde). In unserem Beispiel wird die Datei also <tt>tutorial3ui.rc</tt> heißen. Wo die Datei zu finden ist, wird von CMake erledigt.

===Die ''appname''ui.rc Datei schreiben===

Da die Beschreibung unseres UI mit XML definiert wird, muss der Inhalt der Beschreibung strengen Regeln folgen. Wir werden hier nicht alle Regeln auflisten. Darüber wird es eine gesonderte und detailierte Seite geben (die aber noch nicht fertig ist).

===tutorial3ui.rc===
<code xml n>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<gui name="tutorial3" version="1">

<ToolBar name="mainToolBar" >
<text>Main Toolbar</text>
<Action name="clear" />
<ActionList name="dynamicActionlist" />
</ToolBar>
<MenuBar>
<Menu name="file" >
<text>&File</text>
<Action name="clear" />
</Menu>
</MenuBar>
</gui>
</code>

Das <tt><Toolbar></tt> Tag beschreibt die Werkzeugleiste (der Balken mit Icons am oberen Rand des Fensters). Wir geben dieser hier den eindeutigen Namen ''mainToolBar'', setzen den Namen, der für den Benutzer sichtbar ist, auf ''Main Toolbar'', indem wir das <tt><text></tt> Tag anwenden und fügen letztlich unsere Clear-Aktion in die Werkzeugleiste ein, indem wir das <tt><Action></tt> Tag benutzen. Der Parameter "name" dieses Tags ist die gleiche Zeichenkette, die der <tt>addAction()</tt> Funktion im C++ Code übergeben wurde.

Neben der Werkzeugleiste können wir die Aktion auch in das Hauptmenü einfügen. Dieses erfolgt über das <tt><MenuBar></tt> Tag. Hier wird festgelegt, dass die Aktion in das ''File'' Menü eingefügt werden soll. Die Aktion selber wird auf die gleiche Art und Weise eingefügt wie bereits in der der Werkzeugleiste beschrieben.

Bitte beachten Sie, dass sie auch eine dynamische Aktionsliste in die Konfigurationsdatei einfügen können, wenn Sie das <tt><ActionList></tt> Tag benutzen. Mehr Informationen darüber finden Sie in der Methodenbeschreibung <tt>plugActionList()</tt> der {{class|KXMLGUIClient}} Dokumentation.

Ändern Sie jedesmal das "version" Attribut des Gui-Tags wenn Sie die .rc Datei geändert haben, damit ein Auffrisches des Systemcaches erfolgt.

==CMake==
Da wir jetzt XmlGui benutzen, muß die <tt>tutorial3ui.rc</tt> Datei irgendwo hin kopiert werden, wo KDE sie finden kann. '''Aus diesem Grund muss unser Programm irgendwo hin installiert werden.'''

===CMakeLists.txt===
<code>
project(tutorial3)

find_package(KDE4 REQUIRED)
include_directories( ${KDE4_INCLUDES} )

set(tutorial3_SRCS
main.cpp
mainwindow.cpp
)

kde4_add_executable(tutorial3 ${tutorial3_SRCS})

target_link_libraries(tutorial3 ${KDE4_KDEUI_LIBS})

install(TARGETS tutorial3 DESTINATION ${BIN_INSTALL_DIR})
install( FILES tutorial3ui.rc
DESTINATION ${DATA_INSTALL_DIR}/tutorial3 )
</code>

Diese Datei sieht fast genau so aus wie diejenige für Kapitel2, hat aber zwei extra Zeilen am Ende. Diese beschreiben, wohin die Dateien installiert werden sollen. Zunächst wird das <tt>tutorial3</tt> Ziel in das Verzeichnis <tt>BIN_INSTALL_DIR</tt> Verzeichnis installiert und anschließend die <tt>tutorial3ui.rc</tt> Datei, die das Layout unseres Userinterfaces beschreibt in das Datenverzeichnis unserer Applikation.

===Erzeugen, Installieren und Ausführen===
Wenn Sie keinen Schreibzugriff auf das KDE4 Installationsverzeichnis haben, können Sie das Programm auch in ein Verzeichnis innerhalb Ihres Heimatverzeichnissen installieren.

Um CMake mitzuteilen, wohin das Programm installiert werden soll, setzen Sie den <tt>DCMAKE_INSTALL_PREFIX</tt> Schalter. Um also das Programm in das KDE Verzeichnis zu installieren, rufen Sie
cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
make install
tutorial3
auf.

Wenn man hingegen das Programm irgendwo lokal zu Testzwecken installieren will (bei der zurzeit etwas eingeschränkten Funktionalität unsere Applikation ist es vielleicht nicht unbedingt sinnvoll diese in das KDE Hauptverzeichnis zu installieren), wird mit dem Befehl
cmake . -DCMAKE_INSTALL_PREFIX=/home/kde-devel/kdetmp
eine KDE-artige Verzeichnisstruktur innerhalb des ~/kdetmp Verzeichnissen angelegt und die Applikation in das {{path|/home/kde-devel/kdetmp/bin/tutorial3}} Verzeichnis kopiert.

==Weiter geht's==
TODO

[[Category:C++]]

Development/Tutorials (de)

2007-12-21T11:13:47Z

DrSlowDecay: Changed template to german version

Development/Tutorials/Localization/i18n (de)

2007-12-21T11:01:39Z

DrSlowDecay: More translation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n}}

{{TutorialBrowser (de)|

series=Lokalisation|

pre=[[../Unicode (de)|Introduction to Unicode]] ist empfohlen wenn auch nicht notwendig|

name=Beim Applikationen schreiben an die Lokalisation denken|

next=[[../i18n_Mistakes (de)|Häufige Fehler vermeiden]]|

}}

== Zusammenfassung ==

Eine breite Schar an Benutzern und Entwicklern zu erreichen erfordert, dass Ihre Software übersetzt werden kann und sich auch anderweitig an sprachliche und kulturelle Gegebenheiten desjenigen anpassen kann, der Ihre Applikation benutzt. Das ist die Aufgabe von Lokalisation und diese Anleitung leitet Sie durch die grundlegenden Schritte, Ihre Applikation lokalisierungsfähig zu machen.

== Was ist Internationalisation and Lokalisation? ==

Internationalisation, oder i18n ('i', gefolgt von 18 Buchstaben und dann ein 'n'), bezeichnet den Prozess, Ihre Applikation so zu schreiben, dass sie in jeder beliebigen Sprache und Kultur laufen kann. Dabei müssen folgende Dinge berücksichtigt werden:
* Textmitteilungen, die dem Benutzer mitgeteilt werden
* Dateneingabe vom Benutzer, Dateien und anderen Quellen
* Das Format von Datum, Zahlen, Währungen, etc.

Lokalisation, oder l10n ('l' gefolgt von 10 Zeichen und dann ein 'n') ist der Prozess, eine internationalisierte Applikation an bestimmte lokale Gegebenheiten anzupassen.

Im allgemeinen internationalisieren Programmierer ihre Applikationen und Übersetzerteams lokalisieren sie.

== Warum ist das wichtig? ==

KDE Entwicklung findet primär in Englisch statt, da dies eine breite Entwickler- und Übersetzerschaft erreicht. Englisch ist jedoch nicht die Muttersprache der meisten Menschen auf der Welt. Tatsächlich sprechen weniger als 8% der Menschheit Englisch und weniger als 5% sprechen es als Muttersprache. Auch im Internet benutzen nur 35% der Menschen die online sind Englisch als primäre Sprache und je mehr Teile der Welt an das Internet angeschlossen werden, desto geringer wird dieser Anteil werden. Zusätzlich benutzen die meisten sprachen, alleine 9 der 10 häufigsten, nicht-ASCII Zeichen in ihrer geschriebenen Form. Daher ist es einfach zu erkennen, warum es notwendig ist, Software zu lokalisieren.

Als internationales Projekt das den gesamten Globul umspannt, ist diese Lokalisation ein wichtiges Gut der KDE Kultur. Tatsächlich entwickeln viele KDE Entwickler ihre Applikationen in Englisch benutzen jedoch ihren KDE-Desktop in der jeweils lokalisierten Version.

== Übersetzbaren Code mit i18n() ==

To ensure your application is ready to be localized you have to follow a few simple rules. All user-visible strings in your application should be translated before they are displayed on the user's screen, exceptions to this being debugging messages, configuration keys and similar types of text data.

KDE provides the <tt>KLocale</tt> class as part of <tt>libkdecore</tt> to facilitate the technical details of localization. KLocale makes it as easy as possible for developers to make their code i18n aware, but there are some things you need to be aware of so that applications are usable in other languages and countries.

Access to a global <tt>KLocale</tt> object is provided via <tt>KGlobal::locale()</tt>. This <tt>KLocale</tt> object is created automatically by <tt>KInstance</tt> and takes care of all user i18n related settings. It is deleted automatically on application exit.

Translations are made possible by the <tt>QString i18n(const char*)</tt> method, defined in <tt>klocalizedstring.h</tt>, which you must wrap all strings that should be displayed in. The QString returned by <tt>i18n()</tt> is the translated (if necessary) string. This makes creating translatable widgets as simple as in this example:

<code cppqt>
#include <klocalizedstring.h>
[...]
QPushButton* myButton = new QPushButton(i18n("Translate this!"));</code>

QString's native Unicode support ensures that all translations are represented correctly. All string handling done by your application should therefore use QString.

{{tip|If the string to be translated contains any non-UTF8 characters, use the utf8() method to get a char*.}}

=== ki18n ===

The <tt>i18n()</tt> method requires that a <tt>KInstance</tt> (e.g. <tt>KApplication</tt>) has been created. For any strings that are created prior to this there is another method provided: <tt>ki18n()</tt>. This allows one to mark strings that should be translated later as such. The ki18n() will return a <tt>KLocalizedString</tt>, which can be finalized into a QString (i.e. translated for real) after the KInstance has been created, using its toString() method.

ki18n() is typically used for strings given to KAboutData, because it is constructed before the KApplication and you can use i18n() only after the construction of the KApplication. Other than these special cases, it is always safe to use i18n() if you are sure that the code will be executed after construction of KApplication or some other KInstance.

=== Kontext hinzufügen ===

There is an extended version of <tt>i18n()</tt>, <tt>i18nc()</tt> which takes two <tt>const char*</tt> arguments. The first argument is an additional contextual description of the second string which will be translated. The first string is used to find the proper corresponding translation at run-time and is shown to translators to help them understand the meaning of the string.

Use <tt>i18nc()</tt> whenever the purpose of the text might be ambiguous without further context. For example, consider a context menu in a file manager with an entry called "View" which opens a viewer for the currently selected file. In this context "View" is a verb. However, the same application also may have a menu called "View" in the menubar. In that context "View" is a noun. In the English version of the application everything looks fine, but in most other languages one of the two "View" strings will be incorrect.

Additionally, translators sometimes need extra help in understanding what the text is actually referring to during the translation process.

In the file manager example above, one might therefore write:

<code cppqt>contextMenu->addAction(i18nc("verb, to view something", "View"));
viewMenu->addAction(i18nc("noun, the view", "View"));</code>

Now the two strings will be properly translatable, both by the human translators and at runtime by KLocale.

Use this form of i18n whenever the string to translate is short or the meaning is hard to discern when the context is not exactly known. For example:

<code cppqt>QString up = i18nc("Go one directory up in the hierarchy", "Up");
QString relation = i18nc("A person's name and their familial relationship to you.", "%1 is your %2", name, relationship);</code>

{{note (de)|There is also a ki18nc("context","text") method for providing context to strings which are constructed before the KInstance. It returns a KLocalizedString, so use the toString() method afterwards to convert it into a QString.}}

Contexts can also be added when building forms in Qt Designer. Each widget label, including tooltips and whatsthis texts, has a "comment" attribute, which will serve the same purpose as first argument to <tt>i18nc()</tt> call.

=== Standard Kontext für häufige Ausdrücke ===

Below is a chart showing some common words and phrases in English and the context that must be used with them to ensure proper translation of them in other languages.

{|
|+ Standard Contexts
|-
! Phrase !! Context !! i18nc Call !! Example
|-
| Busy || Refering to a person || <tt>i18nc("A person is busy", "Busy")</tt>
|-
| Busy || Refering to a thing || <tt>i18nc("A thing is busy", "Busy")</tt>
|-
| Color || Color mode, as opposed to Grayscale || <tt>i18nc("Color mode", "Color")</tt>
|-
| Creator || Refering to a person || <tt>i18nc("A person who creates", "Creator")</tt>
|-
| Creator || Refering to software || <tt>i18nc("Software", "Creator")</tt>
|-
| Display || Refering to hardware || <tt>i18nc("Hardware display", "Display")</tt>
|-
| Editor || Refering to a person || <tt>i18nc("A person who edits", "Editor")</tt>
|-
| Editor || Refering to software || <tt>i18nc("Software", "Editor")</tt>
|-
| Line || Refering to drawing || <tt>i18nc("Draw a line", "Line")</tt>
|-
| Line || Refering to text || <tt>i18nc("Line of text", "Line")</tt>
|-
| Name || Refering to a name of thing || <tt>i18nc("A thing's name", "Name") || In theme change dialog: i18nc("Theme name", "Name")</tt>
|-
| Name || Refering to first name and last name of person || <tt>i18nc("Person's first and last name", "Name") || In KAddessbook contact edit dialog: i18nc("Person's first and last name", "Name")</tt>
|-
| No || Answer to a question || <tt>i18nc("Answer to a question", "No")</tt>
|-
| No || Availability of a thing || <tt>i18nc("Availability", "No")</tt>
|-
| (Re)load || (Re)load a document, medium etc. || <tt>i18nc("(Re)load a document", "(Re)load")</tt>
|-
| (Re)load || (Re)start a program, daemon etc. || <tt>i18nc("(Re)start a program", "(Re)load")</tt>
|-
| Title || Refering to a person || <tt>i18nc("A person's title", "Title")</tt>
|-
| Title || Refering to a thing || <tt>i18nc("A thing's title", "Title")</tt>
|-
| Volume || Refering to sound || <tt>i18nc("Sound volume", "Volume")</tt>
|-
| Volume || Refering to a filesystem || <tt>i18nc("Filesystem volume", "Volume")</tt>
|-
| Volume || Refering to books || <tt>i18nc("Book volume", "Volume")</tt>
|-
| Yes || Answer to a question || <tt>i18nc("Answer to a question", "Yes")</tt>
|-
| Yes || Availability of a thing|| <tt>i18nc("Availability", "Yes")</tt>
|}

=== Plural ===

Plurals are handled differently from language to language. Many languages have different plurals for 2, 10, 20, 100, etc. When the string you want translated refers to more than one item, you must use the third form of <tt>i18n</tt>, the <tt>i18np()</tt>. It takes the singular and plural English forms as its first two arguments, followed by any substitution arguments as usual, but at least one of which should be integer-valued. For example:

<code cppqt>msgStr = i18np("1 image in album %2", "%1 images in album %2", numImages, albumName);</code>

<tt>i18np()</tt> gets expanded to as many cases as required by the user's language. In English, this is just two forms while in other languages it may be more, depending on the value of the first integer-valued argument.

Note that this form should be used even if the string always refers to more than one item as some languages use a singular form even when referring to a multiple (typically for 21, 31, etc.). This code:

<code cppqt>i18n("%1 files were deleted", numFilesDeleted);</code>

is therefore incorrect and should instead be:

<code cppqt>i18np("1 file was deleted",
"%1 files were deleted",
numFilesDeleted);</code>

To provide context as well as pluralization, use <tt>i18ncp</tt> as in this example:

<code cppqt>i18ncp("Personal file", "1 file", "%1 files", numFiles);</code>

== Datum und Zahlen formatieren ==

When displaying a number to the user, your program must take care of the decimal separator, thousand separator and currency symbol (if any) being used. These symbols differ from region to region. In English speaking countries a dot (.) is used to separate the fractional part of a number, while in some European countries a comma (,) is used instead. Below is a short summary of functions that will help you format the numbers correctly, taking the local conventions into account for you.

{|
|+ Functions to Format Numbers
|-
! Formats a.. !! From a.. !! Function Prototype
|-
| Number || String || <pre>QString formatNumber( const QString & numStr )</pre>
|-
| Number || Integer, double || <pre>formatNumber( double num,
int precision = -1 )</pre>
|-
| Money || String || <pre>formatMoney( const QString & numStr )</pre>
|-
| Money || Number || <pre>formatMoney( double num,
const QString & currency,
int digits = -1 )</pre>
|-
| Date || String || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Time || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false)</pre>
|-
| Date and time || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat = true,
bool includeSecs = false )</pre>
|}

Similar functions exist to read information provided by the user at runtime in their localized format, e.g. readNumber() or readMoney().

== Kalender ==

Applikationen zu entwickeln, die sich mit Datum und Zeit beschäftigen, zum Beispiel Kalender, ist ein sehr komplexes Gebiet. Nicht nur Zeichenketten die ein Datum oder eine Uhrzeit beinhalten müssen lokal angepasst werden, man muss auch andere Aspekte bedenken, wie zum Beispiel:
* Welcher Dag in der Woche der erste ist (cf int weekStartDay())
* Wieviele Monate in einem Jahr sind
* "Ära"-basierte Kalender
* Ob ein 24-Stunden Zeitformat benutzt wird (cf bool use12Clock())

KLocale stellt neben anderen diese Methoden zur verfügung:

{|
|+ Kalenderdaten Funktionen
|-
! Formats a.. !! From a.. !! Function Prototype
|-
| Date || QDate || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Time || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false )</pre>
|-
| Date and time || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat=true,
bool includeSecs=false )</pre>
|}

{{improve (de)|Mehr Informationen für verschiedene Kalendersysteme geben}}

== Häufige Fallen vermeiden ==
Es gibt eine Reihe von häufigen Problemen die es unmöglich machen, eine Applikation angemessen zu lokalisieren. Im nächsten Kapitel [[../i18n Mistakes (de)|Häufige Fehler in der Lokalisation vermeiden]] lernen Sie mehr darüber und wie man solche Fehler vermeidet.

{{note (de)|Dank geht an Lukáš Tinkl, Matthias Kiefer und Gary Cramblitt für die Originalversion dieser Anleitung.}}

[[Category:Programming]]

Development/Tutorials/Localization/i18n (de)

2007-12-21T10:41:20Z

DrSlowDecay: More translation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n}}

{{TutorialBrowser (de)|

series=Lokalisation|

pre=[[../Unicode (de)|Introduction to Unicode]] ist empfohlen wenn auch nicht notwendig|

name=Beim Applikationen schreiben an die Lokalisation denken|

next=[[../i18n_Mistakes (de)|Häufige Fehler vermeiden]]|

}}

== Zusammenfassung ==

Eine breite Schar an Benutzern und Entwicklern zu erreichen erfordert, dass Ihre Software übersetzt werden kann und sich auch anderweitig an sprachliche und kulturelle Gegebenheiten desjenigen anpassen kann, der Ihre Applikation benutzt. Das ist die Aufgabe von Lokalisation und diese Anleitung leitet Sie durch die grundlegenden Schritte, Ihre Applikation lokalisierungsfähig zu machen.

== Was ist Internationalisation and Lokalisation? ==

Internationalisation, oder i18n ('i', gefolgt von 18 Buchstaben und dann ein 'n'), bezeichnet den Prozess, Ihre Applikation so zu schreiben, dass sie in jeder beliebigen Sprache und Kultur laufen kann. Dabei müssen folgende Dinge berücksichtigt werden:
* Textmitteilungen, die dem Benutzer mitgeteilt werden
* Dateneingabe vom Benutzer, Dateien und anderen Quellen
* Das Format von Datum, Zahlen, Währungen, etc.

Lokalisation, oder l10n ('l' gefolgt von 10 Zeichen und dann ein 'n') ist der Prozess, eine internationalisierte Applikation an bestimmte lokale Gegebenheiten anzupassen.

Im allgemeinen internationalisieren Programmiere ihre Applikationen und Übersetzerteams lokalisieren sie.

== Warum ist das wichtig? ==

KDE development happens primarily in English as this allows the broadest reach into the development and translation communities. However, English is not the primary language of most people on the planet. In fact, fewer than 8% of humanity speaks English and less than 5% speak it as their mother tongue. Even on the Internet, only 35% people who are online use English as their primary language and as more and more of the world gets wired this number is only decreasing. Additionally most languages, including 9 out of the 10 most common languages, use non-ASCII characters in their written form. It is easy to see, then, why it has become a necessity to provide localized software.

As an international project that spans the globe, such localization is a core value within the KDE culture. In fact, while many KDE developers write their software in English they use the desktop in their native locale.

== Übersetzbaren Code mit i18n() ==

To ensure your application is ready to be localized you have to follow a few simple rules. All user-visible strings in your application should be translated before they are displayed on the user's screen, exceptions to this being debugging messages, configuration keys and similar types of text data.

KDE provides the <tt>KLocale</tt> class as part of <tt>libkdecore</tt> to facilitate the technical details of localization. KLocale makes it as easy as possible for developers to make their code i18n aware, but there are some things you need to be aware of so that applications are usable in other languages and countries.

Access to a global <tt>KLocale</tt> object is provided via <tt>KGlobal::locale()</tt>. This <tt>KLocale</tt> object is created automatically by <tt>KInstance</tt> and takes care of all user i18n related settings. It is deleted automatically on application exit.

Translations are made possible by the <tt>QString i18n(const char*)</tt> method, defined in <tt>klocalizedstring.h</tt>, which you must wrap all strings that should be displayed in. The QString returned by <tt>i18n()</tt> is the translated (if necessary) string. This makes creating translatable widgets as simple as in this example:

<code cppqt>
#include <klocalizedstring.h>
[...]
QPushButton* myButton = new QPushButton(i18n("Translate this!"));</code>

QString's native Unicode support ensures that all translations are represented correctly. All string handling done by your application should therefore use QString.

{{tip|If the string to be translated contains any non-UTF8 characters, use the utf8() method to get a char*.}}

=== ki18n ===

The <tt>i18n()</tt> method requires that a <tt>KInstance</tt> (e.g. <tt>KApplication</tt>) has been created. For any strings that are created prior to this there is another method provided: <tt>ki18n()</tt>. This allows one to mark strings that should be translated later as such. The ki18n() will return a <tt>KLocalizedString</tt>, which can be finalized into a QString (i.e. translated for real) after the KInstance has been created, using its toString() method.

ki18n() is typically used for strings given to KAboutData, because it is constructed before the KApplication and you can use i18n() only after the construction of the KApplication. Other than these special cases, it is always safe to use i18n() if you are sure that the code will be executed after construction of KApplication or some other KInstance.

=== Kontext hinzufügen ===

There is an extended version of <tt>i18n()</tt>, <tt>i18nc()</tt> which takes two <tt>const char*</tt> arguments. The first argument is an additional contextual description of the second string which will be translated. The first string is used to find the proper corresponding translation at run-time and is shown to translators to help them understand the meaning of the string.

Use <tt>i18nc()</tt> whenever the purpose of the text might be ambiguous without further context. For example, consider a context menu in a file manager with an entry called "View" which opens a viewer for the currently selected file. In this context "View" is a verb. However, the same application also may have a menu called "View" in the menubar. In that context "View" is a noun. In the English version of the application everything looks fine, but in most other languages one of the two "View" strings will be incorrect.

Additionally, translators sometimes need extra help in understanding what the text is actually referring to during the translation process.

In the file manager example above, one might therefore write:

<code cppqt>contextMenu->addAction(i18nc("verb, to view something", "View"));
viewMenu->addAction(i18nc("noun, the view", "View"));</code>

Now the two strings will be properly translatable, both by the human translators and at runtime by KLocale.

Use this form of i18n whenever the string to translate is short or the meaning is hard to discern when the context is not exactly known. For example:

<code cppqt>QString up = i18nc("Go one directory up in the hierarchy", "Up");
QString relation = i18nc("A person's name and their familial relationship to you.", "%1 is your %2", name, relationship);</code>

{{note (de)|There is also a ki18nc("context","text") method for providing context to strings which are constructed before the KInstance. It returns a KLocalizedString, so use the toString() method afterwards to convert it into a QString.}}

Contexts can also be added when building forms in Qt Designer. Each widget label, including tooltips and whatsthis texts, has a "comment" attribute, which will serve the same purpose as first argument to <tt>i18nc()</tt> call.

=== Standard Kontext für häufige Ausdrücke ===

Below is a chart showing some common words and phrases in English and the context that must be used with them to ensure proper translation of them in other languages.

{|
|+ Standard Contexts
|-
! Phrase !! Context !! i18nc Call !! Example
|-
| Busy || Refering to a person || <tt>i18nc("A person is busy", "Busy")</tt>
|-
| Busy || Refering to a thing || <tt>i18nc("A thing is busy", "Busy")</tt>
|-
| Color || Color mode, as opposed to Grayscale || <tt>i18nc("Color mode", "Color")</tt>
|-
| Creator || Refering to a person || <tt>i18nc("A person who creates", "Creator")</tt>
|-
| Creator || Refering to software || <tt>i18nc("Software", "Creator")</tt>
|-
| Display || Refering to hardware || <tt>i18nc("Hardware display", "Display")</tt>
|-
| Editor || Refering to a person || <tt>i18nc("A person who edits", "Editor")</tt>
|-
| Editor || Refering to software || <tt>i18nc("Software", "Editor")</tt>
|-
| Line || Refering to drawing || <tt>i18nc("Draw a line", "Line")</tt>
|-
| Line || Refering to text || <tt>i18nc("Line of text", "Line")</tt>
|-
| Name || Refering to a name of thing || <tt>i18nc("A thing's name", "Name") || In theme change dialog: i18nc("Theme name", "Name")</tt>
|-
| Name || Refering to first name and last name of person || <tt>i18nc("Person's first and last name", "Name") || In KAddessbook contact edit dialog: i18nc("Person's first and last name", "Name")</tt>
|-
| No || Answer to a question || <tt>i18nc("Answer to a question", "No")</tt>
|-
| No || Availability of a thing || <tt>i18nc("Availability", "No")</tt>
|-
| (Re)load || (Re)load a document, medium etc. || <tt>i18nc("(Re)load a document", "(Re)load")</tt>
|-
| (Re)load || (Re)start a program, daemon etc. || <tt>i18nc("(Re)start a program", "(Re)load")</tt>
|-
| Title || Refering to a person || <tt>i18nc("A person's title", "Title")</tt>
|-
| Title || Refering to a thing || <tt>i18nc("A thing's title", "Title")</tt>
|-
| Volume || Refering to sound || <tt>i18nc("Sound volume", "Volume")</tt>
|-
| Volume || Refering to a filesystem || <tt>i18nc("Filesystem volume", "Volume")</tt>
|-
| Volume || Refering to books || <tt>i18nc("Book volume", "Volume")</tt>
|-
| Yes || Answer to a question || <tt>i18nc("Answer to a question", "Yes")</tt>
|-
| Yes || Availability of a thing|| <tt>i18nc("Availability", "Yes")</tt>
|}

=== Plural ===

Plurals are handled differently from language to language. Many languages have different plurals for 2, 10, 20, 100, etc. When the string you want translated refers to more than one item, you must use the third form of <tt>i18n</tt>, the <tt>i18np()</tt>. It takes the singular and plural English forms as its first two arguments, followed by any substitution arguments as usual, but at least one of which should be integer-valued. For example:

<code cppqt>msgStr = i18np("1 image in album %2", "%1 images in album %2", numImages, albumName);</code>

<tt>i18np()</tt> gets expanded to as many cases as required by the user's language. In English, this is just two forms while in other languages it may be more, depending on the value of the first integer-valued argument.

Note that this form should be used even if the string always refers to more than one item as some languages use a singular form even when referring to a multiple (typically for 21, 31, etc.). This code:

<code cppqt>i18n("%1 files were deleted", numFilesDeleted);</code>

is therefore incorrect and should instead be:

<code cppqt>i18np("1 file was deleted",
"%1 files were deleted",
numFilesDeleted);</code>

To provide context as well as pluralization, use <tt>i18ncp</tt> as in this example:

<code cppqt>i18ncp("Personal file", "1 file", "%1 files", numFiles);</code>

== Datum und Zahlen formatieren ==

When displaying a number to the user, your program must take care of the decimal separator, thousand separator and currency symbol (if any) being used. These symbols differ from region to region. In English speaking countries a dot (.) is used to separate the fractional part of a number, while in some European countries a comma (,) is used instead. Below is a short summary of functions that will help you format the numbers correctly, taking the local conventions into account for you.

{|
|+ Functions to Format Numbers
|-
! Formats a.. !! From a.. !! Function Prototype
|-
| Number || String || <pre>QString formatNumber( const QString & numStr )</pre>
|-
| Number || Integer, double || <pre>formatNumber( double num,
int precision = -1 )</pre>
|-
| Money || String || <pre>formatMoney( const QString & numStr )</pre>
|-
| Money || Number || <pre>formatMoney( double num,
const QString & currency,
int digits = -1 )</pre>
|-
| Date || String || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Time || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false)</pre>
|-
| Date and time || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat = true,
bool includeSecs = false )</pre>
|}

Similar functions exist to read information provided by the user at runtime in their localized format, e.g. readNumber() or readMoney().

== Kalender ==

Developing applications dealing with dates and time, such as calendars, is a very complex area. Not only may the displayed string containing a date or time may look different based on locale, but one also has to take care of other aspects such as:
* which day in the week is the first one (cf int weekStartDay())
* how many months in a year there are
* "era"-based calendars
* whether to use 24-hour time format (cf bool use12Clock())

KLocale provides, among others, these methods:

{|
|+ Calendar Data Functions
|-
! Formats a.. !! From a.. !! Function Prototype
|-
| Date || QDate || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Time || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false )</pre>
|-
| Date and time || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat=true,
bool includeSecs=false )</pre>
|}

{{improve (de)|Mehr Informationen für verschiedene Kalendersysteme geben}}

== Häufige Fallen vermeiden ==
There are a number of common problems that may prevent an application being properly localized. See [[../i18n Mistakes|Avoiding Common Localization Pitfalls]] to learn more about them, and how to avoid them.

{{note (de)|Dank geht an Lukáš Tinkl, Matthias Kiefer und Gary Cramblitt für die Originalversion dieser Anleitung.}}

[[Category:Programming]]

Template:Improve (de)

2007-12-21T10:28:43Z

DrSlowDecay: Created template

{{Warning (de)|
'''Dieser Abschnitt muss verbessert werden''': Bitte hilf mit, verwirrende Abschnitte zu ''bereinigen'' und ''Abschnitte zu reparieren'' die ein '''todo''' beinhalten
 {{{1|}}}  }}
<noinclude>[[Category:Maintenance Templates]] [[Category:Template]]</noinclude>

Template:Warning (de)

2007-12-21T10:25:06Z

DrSlowDecay: Created template

{{Box|1={{{3|Warnung}}}|2=[[Image:Action_stop.svg|noframe|left|40px]]{{{1}}} <div class="clear"></div> }}
<noinclude>
[[Category:Template]]
</noinclude>

Template:Note (de)

2007-12-21T10:21:36Z

DrSlowDecay: Created template

{{Box|Anmerkung|2=[[Image:Action_pen.svg|noframe|left|40px]]{{{1}}} <div class="clear"></div> }}
<noinclude>
[[Category:Template]]
</noinclude>

Development/Tutorials/Localization/i18n (de)

2007-12-21T10:13:22Z

DrSlowDecay: Page created and first translations

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n}}

{{TutorialBrowser (de)|

series=Lokalisation|

pre=[[../Unicode|Introduction to Unicode (de)]] ist empfohlen wenn auch nicht notwendig|

name=Applikationen schreiben und dabei an die Lokalisation denken|

next=[[../i18n_Mistakes (de)|Häufige Fehler vermeiden]]|

}}

== Zusammenfassung ==

Reaching a broad audience of users and developers requires that your software can be translated and otherwise shaped at runtime to be linguistically and culturally relevant to whomever is sitting in front of the computer. This is the realm of localization and this tutorial steps you through what is needed to make your application localizable.

== Was ist Internationalisation and Lokalisation? ==

Internationalization, or i18n ('i', followed by 18 letters, then an 'n'), is the process of writing your application so that it can be run in any locale. This means taking into account such things as:
* textual messages that are displayed to the user
* data input from the user, files and other sources
* format of dates, numbers, currency, dates, etc.

Localization, or l10n ('l', followed by 10 characters, then an 'n'), is the process of taking an internationalized application and adapting it for a specific locale.

Generaly speaking, programmers internationalize their applications and translation teams localize them.

== Warum ist das wichtig? ==

KDE development happens primarily in English as this allows the broadest reach into the development and translation communities. However, English is not the primary language of most people on the planet. In fact, fewer than 8% of humanity speaks English and less than 5% speak it as their mother tongue. Even on the Internet, only 35% people who are online use English as their primary language and as more and more of the world gets wired this number is only decreasing. Additionally most languages, including 9 out of the 10 most common languages, use non-ASCII characters in their written form. It is easy to see, then, why it has become a necessity to provide localized software.

As an international project that spans the globe, such localization is a core value within the KDE culture. In fact, while many KDE developers write their software in English they use the desktop in their native locale.

== Übersetzbaren Code mit i18n() ==

To ensure your application is ready to be localized you have to follow a few simple rules. All user-visible strings in your application should be translated before they are displayed on the user's screen, exceptions to this being debugging messages, configuration keys and similar types of text data.

KDE provides the <tt>KLocale</tt> class as part of <tt>libkdecore</tt> to facilitate the technical details of localization. KLocale makes it as easy as possible for developers to make their code i18n aware, but there are some things you need to be aware of so that applications are usable in other languages and countries.

Access to a global <tt>KLocale</tt> object is provided via <tt>KGlobal::locale()</tt>. This <tt>KLocale</tt> object is created automatically by <tt>KInstance</tt> and takes care of all user i18n related settings. It is deleted automatically on application exit.

Translations are made possible by the <tt>QString i18n(const char*)</tt> method, defined in <tt>klocalizedstring.h</tt>, which you must wrap all strings that should be displayed in. The QString returned by <tt>i18n()</tt> is the translated (if necessary) string. This makes creating translatable widgets as simple as in this example:

<code cppqt>
#include <klocalizedstring.h>
[...]
QPushButton* myButton = new QPushButton(i18n("Translate this!"));</code>

QString's native Unicode support ensures that all translations are represented correctly. All string handling done by your application should therefore use QString.

{{tip|If the string to be translated contains any non-UTF8 characters, use the utf8() method to get a char*.}}

=== ki18n ===

The <tt>i18n()</tt> method requires that a <tt>KInstance</tt> (e.g. <tt>KApplication</tt>) has been created. For any strings that are created prior to this there is another method provided: <tt>ki18n()</tt>. This allows one to mark strings that should be translated later as such. The ki18n() will return a <tt>KLocalizedString</tt>, which can be finalized into a QString (i.e. translated for real) after the KInstance has been created, using its toString() method.

ki18n() is typically used for strings given to KAboutData, because it is constructed before the KApplication and you can use i18n() only after the construction of the KApplication. Other than these special cases, it is always safe to use i18n() if you are sure that the code will be executed after construction of KApplication or some other KInstance.

=== Kontext hinzufügen ===

There is an extended version of <tt>i18n()</tt>, <tt>i18nc()</tt> which takes two <tt>const char*</tt> arguments. The first argument is an additional contextual description of the second string which will be translated. The first string is used to find the proper corresponding translation at run-time and is shown to translators to help them understand the meaning of the string.

Use <tt>i18nc()</tt> whenever the purpose of the text might be ambiguous without further context. For example, consider a context menu in a file manager with an entry called "View" which opens a viewer for the currently selected file. In this context "View" is a verb. However, the same application also may have a menu called "View" in the menubar. In that context "View" is a noun. In the English version of the application everything looks fine, but in most other languages one of the two "View" strings will be incorrect.

Additionally, translators sometimes need extra help in understanding what the text is actually referring to during the translation process.

In the file manager example above, one might therefore write:

<code cppqt>contextMenu->addAction(i18nc("verb, to view something", "View"));
viewMenu->addAction(i18nc("noun, the view", "View"));</code>

Now the two strings will be properly translatable, both by the human translators and at runtime by KLocale.

Use this form of i18n whenever the string to translate is short or the meaning is hard to discern when the context is not exactly known. For example:

<code cppqt>QString up = i18nc("Go one directory up in the hierarchy", "Up");
QString relation = i18nc("A person's name and their familial relationship to you.", "%1 is your %2", name, relationship);</code>

{{note|There is also a ki18nc("context","text") method for providing context to strings which are constructed before the KInstance. It returns a KLocalizedString, so use the toString() method afterwards to convert it into a QString.}}

Contexts can also be added when building forms in Qt Designer. Each widget label, including tooltips and whatsthis texts, has a "comment" attribute, which will serve the same purpose as first argument to <tt>i18nc()</tt> call.

=== Standard Kontext für häufige Ausdrücke ===

Below is a chart showing some common words and phrases in English and the context that must be used with them to ensure proper translation of them in other languages.

{|
|+ Standard Contexts
|-
! Phrase !! Context !! i18nc Call !! Example
|-
| Busy || Refering to a person || <tt>i18nc("A person is busy", "Busy")</tt>
|-
| Busy || Refering to a thing || <tt>i18nc("A thing is busy", "Busy")</tt>
|-
| Color || Color mode, as opposed to Grayscale || <tt>i18nc("Color mode", "Color")</tt>
|-
| Creator || Refering to a person || <tt>i18nc("A person who creates", "Creator")</tt>
|-
| Creator || Refering to software || <tt>i18nc("Software", "Creator")</tt>
|-
| Display || Refering to hardware || <tt>i18nc("Hardware display", "Display")</tt>
|-
| Editor || Refering to a person || <tt>i18nc("A person who edits", "Editor")</tt>
|-
| Editor || Refering to software || <tt>i18nc("Software", "Editor")</tt>
|-
| Line || Refering to drawing || <tt>i18nc("Draw a line", "Line")</tt>
|-
| Line || Refering to text || <tt>i18nc("Line of text", "Line")</tt>
|-
| Name || Refering to a name of thing || <tt>i18nc("A thing's name", "Name") || In theme change dialog: i18nc("Theme name", "Name")</tt>
|-
| Name || Refering to first name and last name of person || <tt>i18nc("Person's first and last name", "Name") || In KAddessbook contact edit dialog: i18nc("Person's first and last name", "Name")</tt>
|-
| No || Answer to a question || <tt>i18nc("Answer to a question", "No")</tt>
|-
| No || Availability of a thing || <tt>i18nc("Availability", "No")</tt>
|-
| (Re)load || (Re)load a document, medium etc. || <tt>i18nc("(Re)load a document", "(Re)load")</tt>
|-
| (Re)load || (Re)start a program, daemon etc. || <tt>i18nc("(Re)start a program", "(Re)load")</tt>
|-
| Title || Refering to a person || <tt>i18nc("A person's title", "Title")</tt>
|-
| Title || Refering to a thing || <tt>i18nc("A thing's title", "Title")</tt>
|-
| Volume || Refering to sound || <tt>i18nc("Sound volume", "Volume")</tt>
|-
| Volume || Refering to a filesystem || <tt>i18nc("Filesystem volume", "Volume")</tt>
|-
| Volume || Refering to books || <tt>i18nc("Book volume", "Volume")</tt>
|-
| Yes || Answer to a question || <tt>i18nc("Answer to a question", "Yes")</tt>
|-
| Yes || Availability of a thing|| <tt>i18nc("Availability", "Yes")</tt>
|}

=== Plural ===

Plurals are handled differently from language to language. Many languages have different plurals for 2, 10, 20, 100, etc. When the string you want translated refers to more than one item, you must use the third form of <tt>i18n</tt>, the <tt>i18np()</tt>. It takes the singular and plural English forms as its first two arguments, followed by any substitution arguments as usual, but at least one of which should be integer-valued. For example:

<code cppqt>msgStr = i18np("1 image in album %2", "%1 images in album %2", numImages, albumName);</code>

<tt>i18np()</tt> gets expanded to as many cases as required by the user's language. In English, this is just two forms while in other languages it may be more, depending on the value of the first integer-valued argument.

Note that this form should be used even if the string always refers to more than one item as some languages use a singular form even when referring to a multiple (typically for 21, 31, etc.). This code:

<code cppqt>i18n("%1 files were deleted", numFilesDeleted);</code>

is therefore incorrect and should instead be:

<code cppqt>i18np("1 file was deleted",
"%1 files were deleted",
numFilesDeleted);</code>

To provide context as well as pluralization, use <tt>i18ncp</tt> as in this example:

<code cppqt>i18ncp("Personal file", "1 file", "%1 files", numFiles);</code>

== Datum und Zahlen formatieren ==

When displaying a number to the user, your program must take care of the decimal separator, thousand separator and currency symbol (if any) being used. These symbols differ from region to region. In English speaking countries a dot (.) is used to separate the fractional part of a number, while in some European countries a comma (,) is used instead. Below is a short summary of functions that will help you format the numbers correctly, taking the local conventions into account for you.

{|
|+ Functions to Format Numbers
|-
! Formats a.. !! From a.. !! Function Prototype
|-
| Number || String || <pre>QString formatNumber( const QString & numStr )</pre>
|-
| Number || Integer, double || <pre>formatNumber( double num,
int precision = -1 )</pre>
|-
| Money || String || <pre>formatMoney( const QString & numStr )</pre>
|-
| Money || Number || <pre>formatMoney( double num,
const QString & currency,
int digits = -1 )</pre>
|-
| Date || String || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Time || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false)</pre>
|-
| Date and time || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat = true,
bool includeSecs = false )</pre>
|}

Similar functions exist to read information provided by the user at runtime in their localized format, e.g. readNumber() or readMoney().

== Kalender ==

Developing applications dealing with dates and time, such as calendars, is a very complex area. Not only may the displayed string containing a date or time may look different based on locale, but one also has to take care of other aspects such as:
* which day in the week is the first one (cf int weekStartDay())
* how many months in a year there are
* "era"-based calendars
* whether to use 24-hour time format (cf bool use12Clock())

KLocale provides, among others, these methods:

{|
|+ Calendar Data Functions
|-
! Formats a.. !! From a.. !! Function Prototype
|-
| Date || QDate || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Time || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false )</pre>
|-
| Date and time || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat=true,
bool includeSecs=false )</pre>
|}

{{improve|Mehr Informationen für verschiedene Kalendersysteme geben}}

== Häufige Fallen vermeiden ==
There are a number of common problems that may prevent an application being properly localized. See [[../i18n Mistakes|Avoiding Common Localization Pitfalls]] to learn more about them, and how to avoid them.

{{note|Dank geht an Lukáš Tinkl, Matthias Kiefer und Gary Cramblitt für die Originalversion dieser Anleitung.}}

[[Category:Programming]]

Development/Tutorials/Localization/i18n

2007-12-21T10:07:35Z

DrSlowDecay: Added language navigation

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n}}

{{TutorialBrowser|

series=Localization|

pre=[[../Unicode|Introduction to Unicode]] is recommended, though not required|

name=Writing Applications With Localization In Mind|

next=[[../i18n_Mistakes|Avoiding Common Localization Pitfalls]]|

}}

== Abstract ==

Reaching a broad audience of users and developers requires that your software can be translated and otherwise shaped at runtime to be linguistically and culturally relevant to whomever is sitting in front of the computer. This is the realm of localization and this tutorial steps you through what is needed to make your application localizable.

== What is Internationalization and Localization? ==

Internationalization, or i18n ('i', followed by 18 letters, then an 'n'), is the process of writing your application so that it can be run in any locale. This means taking into account such things as:
* textual messages that are displayed to the user
* data input from the user, files and other sources
* format of dates, numbers, currency, dates, etc.

Localization, or l10n ('l', followed by 10 characters, then an 'n'), is the process of taking an internationalized application and adapting it for a specific locale.

Generaly speaking, programmers internationalize their applications and translation teams localize them.

== Why is This Important? ==

KDE development happens primarily in English as this allows the broadest reach into the development and translation communities. However, English is not the primary language of most people on the planet. In fact, fewer than 8% of humanity speaks English and less than 5% speak it as their mother tongue. Even on the Internet, only 35% people who are online use English as their primary language and as more and more of the world gets wired this number is only decreasing. Additionally most languages, including 9 out of the 10 most common languages, use non-ASCII characters in their written form. It is easy to see, then, why it has become a necessity to provide localized software.

As an international project that spans the globe, such localization is a core value within the KDE culture. In fact, while many KDE developers write their software in English they use the desktop in their native locale.

== Translatable Code Using i18n() ==

To ensure your application is ready to be localized you have to follow a few simple rules. All user-visible strings in your application should be translated before they are displayed on the user's screen, exceptions to this being debugging messages, configuration keys and similar types of text data.

KDE provides the <tt>KLocale</tt> class as part of <tt>libkdecore</tt> to facilitate the technical details of localization. KLocale makes it as easy as possible for developers to make their code i18n aware, but there are some things you need to be aware of so that applications are usable in other languages and countries.

Access to a global <tt>KLocale</tt> object is provided via <tt>KGlobal::locale()</tt>. This <tt>KLocale</tt> object is created automatically by <tt>KInstance</tt> and takes care of all user i18n related settings. It is deleted automatically on application exit.

Translations are made possible by the <tt>QString i18n(const char*)</tt> method, defined in <tt>klocalizedstring.h</tt>, which you must wrap all strings that should be displayed in. The QString returned by <tt>i18n()</tt> is the translated (if necessary) string. This makes creating translatable widgets as simple as in this example:

<code cppqt>
#include <klocalizedstring.h>
[...]
QPushButton* myButton = new QPushButton(i18n("Translate this!"));</code>

QString's native Unicode support ensures that all translations are represented correctly. All string handling done by your application should therefore use QString.

{{tip|If the string to be translated contains any non-UTF8 characters, use the utf8() method to get a char*.}}

=== ki18n ===

The <tt>i18n()</tt> method requires that a <tt>KInstance</tt> (e.g. <tt>KApplication</tt>) has been created. For any strings that are created prior to this there is another method provided: <tt>ki18n()</tt>. This allows one to mark strings that should be translated later as such. The ki18n() will return a <tt>KLocalizedString</tt>, which can be finalized into a QString (i.e. translated for real) after the KInstance has been created, using its toString() method.

ki18n() is typically used for strings given to KAboutData, because it is constructed before the KApplication and you can use i18n() only after the construction of the KApplication. Other than these special cases, it is always safe to use i18n() if you are sure that the code will be executed after construction of KApplication or some other KInstance.

=== Adding Context ===

There is an extended version of <tt>i18n()</tt>, <tt>i18nc()</tt> which takes two <tt>const char*</tt> arguments. The first argument is an additional contextual description of the second string which will be translated. The first string is used to find the proper corresponding translation at run-time and is shown to translators to help them understand the meaning of the string.

Use <tt>i18nc()</tt> whenever the purpose of the text might be ambiguous without further context. For example, consider a context menu in a file manager with an entry called "View" which opens a viewer for the currently selected file. In this context "View" is a verb. However, the same application also may have a menu called "View" in the menubar. In that context "View" is a noun. In the English version of the application everything looks fine, but in most other languages one of the two "View" strings will be incorrect.

Additionally, translators sometimes need extra help in understanding what the text is actually referring to during the translation process.

In the file manager example above, one might therefore write:

<code cppqt>contextMenu->addAction(i18nc("verb, to view something", "View"));
viewMenu->addAction(i18nc("noun, the view", "View"));</code>

Now the two strings will be properly translatable, both by the human translators and at runtime by KLocale.

Use this form of i18n whenever the string to translate is short or the meaning is hard to discern when the context is not exactly known. For example:

<code cppqt>QString up = i18nc("Go one directory up in the hierarchy", "Up");
QString relation = i18nc("A person's name and their familial relationship to you.", "%1 is your %2", name, relationship);</code>

{{note|There is also a ki18nc("context","text") method for providing context to strings which are constructed before the KInstance. It returns a KLocalizedString, so use the toString() method afterwards to convert it into a QString.}}

Contexts can also be added when building forms in Qt Designer. Each widget label, including tooltips and whatsthis texts, has a "comment" attribute, which will serve the same purpose as first argument to <tt>i18nc()</tt> call.

=== Standard Context For Common Phrases ===

Below is a chart showing some common words and phrases in English and the context that must be used with them to ensure proper translation of them in other languages.

{|
|+ Standard Contexts
|-
! Phrase !! Context !! i18nc Call !! Example
|-
| Busy || Refering to a person || <tt>i18nc("A person is busy", "Busy")</tt>
|-
| Busy || Refering to a thing || <tt>i18nc("A thing is busy", "Busy")</tt>
|-
| Color || Color mode, as opposed to Grayscale || <tt>i18nc("Color mode", "Color")</tt>
|-
| Creator || Refering to a person || <tt>i18nc("A person who creates", "Creator")</tt>
|-
| Creator || Refering to software || <tt>i18nc("Software", "Creator")</tt>
|-
| Display || Refering to hardware || <tt>i18nc("Hardware display", "Display")</tt>
|-
| Editor || Refering to a person || <tt>i18nc("A person who edits", "Editor")</tt>
|-
| Editor || Refering to software || <tt>i18nc("Software", "Editor")</tt>
|-
| Line || Refering to drawing || <tt>i18nc("Draw a line", "Line")</tt>
|-
| Line || Refering to text || <tt>i18nc("Line of text", "Line")</tt>
|-
| Name || Refering to a name of thing || <tt>i18nc("A thing's name", "Name") || In theme change dialog: i18nc("Theme name", "Name")</tt>
|-
| Name || Refering to first name and last name of person || <tt>i18nc("Person's first and last name", "Name") || In KAddessbook contact edit dialog: i18nc("Person's first and last name", "Name")</tt>
|-
| No || Answer to a question || <tt>i18nc("Answer to a question", "No")</tt>
|-
| No || Availability of a thing || <tt>i18nc("Availability", "No")</tt>
|-
| (Re)load || (Re)load a document, medium etc. || <tt>i18nc("(Re)load a document", "(Re)load")</tt>
|-
| (Re)load || (Re)start a program, daemon etc. || <tt>i18nc("(Re)start a program", "(Re)load")</tt>
|-
| Title || Refering to a person || <tt>i18nc("A person's title", "Title")</tt>
|-
| Title || Refering to a thing || <tt>i18nc("A thing's title", "Title")</tt>
|-
| Volume || Refering to sound || <tt>i18nc("Sound volume", "Volume")</tt>
|-
| Volume || Refering to a filesystem || <tt>i18nc("Filesystem volume", "Volume")</tt>
|-
| Volume || Refering to books || <tt>i18nc("Book volume", "Volume")</tt>
|-
| Yes || Answer to a question || <tt>i18nc("Answer to a question", "Yes")</tt>
|-
| Yes || Availability of a thing|| <tt>i18nc("Availability", "Yes")</tt>
|}

=== Plurals ===

Plurals are handled differently from language to language. Many languages have different plurals for 2, 10, 20, 100, etc. When the string you want translated refers to more than one item, you must use the third form of <tt>i18n</tt>, the <tt>i18np()</tt>. It takes the singular and plural English forms as its first two arguments, followed by any substitution arguments as usual, but at least one of which should be integer-valued. For example:

<code cppqt>msgStr = i18np("1 image in album %2", "%1 images in album %2", numImages, albumName);</code>

<tt>i18np()</tt> gets expanded to as many cases as required by the user's language. In English, this is just two forms while in other languages it may be more, depending on the value of the first integer-valued argument.

Note that this form should be used even if the string always refers to more than one item as some languages use a singular form even when referring to a multiple (typically for 21, 31, etc.). This code:

<code cppqt>i18n("%1 files were deleted", numFilesDeleted);</code>

is therefore incorrect and should instead be:

<code cppqt>i18np("1 file was deleted",
"%1 files were deleted",
numFilesDeleted);</code>

To provide context as well as pluralization, use <tt>i18ncp</tt> as in this example:

<code cppqt>i18ncp("Personal file", "1 file", "%1 files", numFiles);</code>

== Formatting Dates and Numbers ==

When displaying a number to the user, your program must take care of the decimal separator, thousand separator and currency symbol (if any) being used. These symbols differ from region to region. In English speaking countries a dot (.) is used to separate the fractional part of a number, while in some European countries a comma (,) is used instead. Below is a short summary of functions that will help you format the numbers correctly, taking the local conventions into account for you.

{|
|+ Functions to Format Numbers
|-
! Formats a.. !! From a.. !! Function Prototype
|-
| Number || String || <pre>QString formatNumber( const QString & numStr )</pre>
|-
| Number || Integer, double || <pre>formatNumber( double num,
int precision = -1 )</pre>
|-
| Money || String || <pre>formatMoney( const QString & numStr )</pre>
|-
| Money || Number || <pre>formatMoney( double num,
const QString & currency,
int digits = -1 )</pre>
|-
| Date || String || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Time || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false)</pre>
|-
| Date and time || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat = true,
bool includeSecs = false )</pre>
|}

Similar functions exist to read information provided by the user at runtime in their localized format, e.g. readNumber() or readMoney().

== Calendaring ==

Developing applications dealing with dates and time, such as calendars, is a very complex area. Not only may the displayed string containing a date or time may look different based on locale, but one also has to take care of other aspects such as:
* which day in the week is the first one (cf int weekStartDay())
* how many months in a year there are
* "era"-based calendars
* whether to use 24-hour time format (cf bool use12Clock())

KLocale provides, among others, these methods:

{|
|+ Calendar Data Functions
|-
! Formats a.. !! From a.. !! Function Prototype
|-
| Date || QDate || <pre>formatDate( const QDate & pDate,
bool shortFormat=false )</pre>
|-
| Time || QTime || <pre>formatTime( const QTime & pTime,
bool includeSecs=false )</pre>
|-
| Date and time || QDateTime || <pre>formatDateTime( const QDateTime &pDateTime,
bool shortFormat=true,
bool includeSecs=false )</pre>
|}

{{improve|provide more info on the different calendar systems}}

== Avoiding Common Traps ==
There are a number of common problems that may prevent an application being properly localized. See [[../i18n Mistakes|Avoiding Common Localization Pitfalls]] to learn more about them, and how to avoid them.

{{note|Thanks to Lukáš Tinkl, Matthias Kiefer and Gary Cramblitt for writing the original version of this tutorial.}}

[[Category:Programming]]

Development/Tutorials (de)

2007-12-21T10:06:05Z

DrSlowDecay: Added "Lokalisation"

{{Template:I18n/Language Navigation Bar|Development/Tutorials}}

{{improve|Bitte hilf, die englische Seite vollständig ins Deutsche zu übersetzen.}}

== Einführung in die KDE 4 Programmierung ==
Sind Sie an der Entwicklung von Programmen für KDE 4 interesiert? Wenn ja sind Sie hier genau richtig. Diese Artikelserie richtet sich an alle, die noch nie mit KDE programmiert haben.
;[[Development/Tutorials/First program (de)|Hallo Welt!]]
:''Einführung in die Grundlagen der KDE Programmierung''

;[[Development/Tutorials/Using KXmlGuiWindow (de)|Erstellen eines Hauptfensters]]
:''Dieser Artikel erklärt, wie der wichtigste Teil eines grafischen Programmes erstellt wird: das Hauptfenster.''

;[[Development/Tutorials/Using KActions (de)|Die Verwendung von KActions]]
:''In diesem Artikel erfahren Sie, wie Aktionen und Werkzeugleisten (Toolbars) im Menü hinzugefügt werden können.''

== Grundlagen ==
;[[Development/Tutorials/KDE4 Porting Guide (de)|Ihre Applikation nach KDE 4 portieren]]
:''Anleitungen Qt3/KDE3 Applikationen nach Qt4/KDE4 zu portieren''

;[[Development/Tutorials/CMake (de)|Einführung in CMake]]
:''Wie man CMake in KDE 4 benutzt''

;[[Development/Tutorials/Common Programming Mistakes (de)|Häufige Programmierfehler]]
:''Einige häufige Fehler die man während der Entwicklung von Qt und KDE Applikationen machen kann und wie man sie vermeidet.''

;[[Development/Tutorials/Using Qt Designer (de)|Den Qt Designer benutzen um Benutzerschnittstellen zu erzeugen]]
:''Wie man UI Dateien mit dem Designer erzeugt und wie man diese in einem KDE Programm integriert.''

== Dienste: Applicationen and Plugins ==
;[[Development/Tutorials/Services/Introduction (de)|Einführung in das Dienst-Framework]]
:''Eine Einführung über das Dienst-Framework in KDE und was es dem Applikationsentwickler zur Verfügung stellen kann. Beschäftigt sich mit dem system configuration cache (SyCoCa), den benötigten Dateien und wie indizierte Informationen benutzt werden.

;[[Development/Tutorials/Services/Traders (de)|Dienste über Trader Queries finden]]
:''Wie man mit der Trader Query Syntax Dienste wie Plugins oder Mimetypes findet, die im SyCoCa zwischengespeichert wurden. ''

;[[Development/Tutorials/Services/Plugins (de)|Erstellen und Laden von Plugins mit KService]]
:''Zeigt, wie man eigene Plugintypen definiert, installiere Plugins findet (einschließlich denen von anderen Herstellern) und wie man diese einfach und portabel läd, indem man KService benutzt.''

== Lokalisation ==
;[[Development/Tutorials/Localization/Unicode (de)|Einführung in Unicode]]
:''Eine Einführung was Unicode ist und wie KDE Applikationen damit umgehen.''