--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Orb/Doxygen/doc/language.doc Thu Jan 21 17:29:01 2010 +0000
@@ -0,0 +1,728 @@
+/******************************************************************************
+ * Do not edit this file. It was generated by the translator.py script.
+ *
+ * Copyright (C) 1997-2006 by Dimitri van Heesch.
+ *
+ * Permission to use, copy, modify, and distribute this software and its
+ * documentation under the terms of the GNU General Public License is hereby
+ * granted. No representations are made about the suitability of this software
+ * for any purpose. It is provided "as is" without express or implied warranty.
+ * See the GNU General Public License for more details.
+ *
+ * Documents produced by Doxygen are derivative works derived from the
+ * input used in their production; they are not affected by this license.
+ *
+ * $Id: language.doc 713 2009-12-22 16:03:24Z dimitri $
+ */
+/*! \page langhowto Internationalization
+
+<h3>Support for multiple languages</h3>
+
+Doxygen has built-in support for multiple languages. This means that the
+text fragments, generated by doxygen, can be produced in languages other
+than English (the default). The output language is chosen through the
+configuration file (with default name and known as Doxyfile).
+
+Currently (version 1.6.1), 38 languages
+are supported (sorted alphabetically):
+Afrikaans, Arabic, Brazilian Portuguese, Catalan, Chinese, Chinese
+Traditional, Croatian, Czech, Danish, Dutch, English, Esperanto,
+Finnish, French, German, Greek, Hungarian, Indonesian, Italian,
+Japanese (+En), Korean (+En), Lithuanian, Macedonian, Norwegian,
+Persian, Polish, Portuguese, Romanian, Russian, Serbian,
+SerbianCyrilic, Slovak, Slovene, Spanish, Swedish, Turkish, Ukrainian,
+and Vietnamese..
+
+The table of information related to the supported languages follows.
+It is sorted by language alphabetically. The <b>Status</b> column
+was generated from sources and shows approximately the last version
+when the translator was updated.
+
+\htmlonly
+<table align="center" cellspacing="0" cellpadding="0" border="0">
+<tr bgcolor="#000000">
+<td>
+ <table cellspacing="1" cellpadding="2" border="0">
+ <tr bgcolor="#4040c0">
+ <td ><b><font size="+1" color="#ffffff"> Language </font></b></td>
+ <td ><b><font size="+1" color="#ffffff"> Maintainer </font></b></td>
+ <td ><b><font size="+1" color="#ffffff"> Contact address </font>
+ <font size="-2" color="#ffffff">(replace the at and dot)</font></b></td>
+ <td ><b><font size="+1" color="#ffffff"> Status </font></b></td>
+ </tr>
+ <!-- table content begin -->
+
+ <tr bgcolor="#ffffff">
+ <td>Afrikaans</td>
+ <td>Johan Prinsloo</td>
+ <td>johan at zippysnoek dot com</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Arabic</td>
+ <td>Moaz Reyad</td>
+ <td>moazreyad at yahoo dot com</td>
+ <td>1.4.6</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Brazilian Portuguese</td>
+ <td>Fabio "FJTC" Jun Takada Chino</td>
+ <td>jun-chino at uol dot com dot br</td>
+ <td>up-to-date</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Catalan</td>
+ <td>Maximiliano Pin<br/>Albert Mora</td>
+ <td>max.pin at bitroit dot com<br/>amora at iua dot upf dot es</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Chinese</td>
+ <td>Li Daobing<br/>Wei Liu</td>
+ <td>lidaobing at gmail dot com<br/>liuwei at asiainfo dot com</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Chinese Traditional</td>
+ <td>Daniel YC Lin<br/>Gary Lee</td>
+ <td>dlin.tw at gmail dot com<br/>garywlee at gmail dot com</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Croatian</td>
+ <td>Boris Bralo</td>
+ <td>boris.bralo at zg dot htnet dot hr</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Czech</td>
+ <td>Petr Přikryl</td>
+ <td>prikrylp at skil dot cz</td>
+ <td>up-to-date</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Danish</td>
+ <td>Erik Søe Sørensen</td>
+ <td>eriksoe+doxygen at daimi dot au dot dk</td>
+ <td>1.5.4</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Dutch</td>
+ <td>Dimitri van Heesch</td>
+ <td>dimitri at stack dot nl</td>
+ <td>up-to-date</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>English</td>
+ <td>Dimitri van Heesch</td>
+ <td>dimitri at stack dot nl</td>
+ <td>up-to-date</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Esperanto</td>
+ <td>Ander Martinez</td>
+ <td>dwarfnauko at gmail dot com</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Finnish</td>
+ <td>Antti Laine</td>
+ <td>antti.a.laine at tut dot fi</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>French</td>
+ <td>Xavier Outhier</td>
+ <td>xouthier at yahoo dot fr</td>
+ <td>up-to-date</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>German</td>
+ <td>Jens Seidel</td>
+ <td>jensseidel at users dot sf dot net</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Greek</td>
+ <td>Paul Gessos</td>
+ <td>nickreserved at yahoo dot com</td>
+ <td>1.5.4</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Hungarian</td>
+ <td>Ákos Kiss<br/>Földvári György</td>
+ <td>akiss at users dot sourceforge dot net<br/>foldvari lost at cyberspace</td>
+ <td>1.4.6</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Indonesian</td>
+ <td>Hendy Irawan</td>
+ <td>ceefour at gauldong dot net</td>
+ <td>1.4.6</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Italian</td>
+ <td>Alessandro Falappa<br/>Ahmed Aldo Faisal</td>
+ <td>alessandro at falappa dot net<br/>aaf23 at cam dot ac dot uk</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Japanese</td>
+ <td>Hiroki Iseri<br/>Ryunosuke Satoh<br/>Kenji Nagamatsu<br/>Iwasa Kazmi</td>
+ <td>goyoki at gmail dot com<br/>sun594 at hotmail dot com<br/>naga at joyful dot club dot ne dot jp<br/>iwasa at cosmo-system dot jp</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>JapaneseEn</td>
+ <td>see the Japanese language</td>
+ <td> </td>
+ <td>English based</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Korean</td>
+ <td>Kim Taedong<br/>SooYoung Jung<br/>Richard Kim</td>
+ <td>fly1004 at gmail dot com<br/>jung5000 at gmail dot com<br/>ryk at dspwiz dot com</td>
+ <td>up-to-date</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>KoreanEn</td>
+ <td>see the Korean language</td>
+ <td> </td>
+ <td>English based</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Lithuanian</td>
+ <td>Tomas Simonaitis<br/>Mindaugas Radzius<br/>Aidas Berukstis</td>
+ <td>haden at homelan dot lt<br/>mindaugasradzius at takas dot lt<br/>aidasber at takas dot lt</td>
+ <td>1.4.6</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Macedonian</td>
+ <td>Slave Jovanovski</td>
+ <td>slavejovanovski at yahoo dot com</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Norwegian</td>
+ <td>Lars Erik Jordet</td>
+ <td>lejordet at gmail dot com</td>
+ <td>1.4.6</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Persian</td>
+ <td>Ali Nadalizadeh</td>
+ <td>nadalizadeh at gmail dot com</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Polish</td>
+ <td>Piotr Kaminski<br/>Grzegorz Kowal<br/>Krzysztof Kral</td>
+ <td>Piotr.Kaminski at ctm dot gdynia dot pl<br/>g_kowal at poczta dot onet dot pl<br/>krzysztof.kral at gmail dot com</td>
+ <td>up-to-date</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Portuguese</td>
+ <td>Rui Godinho Lopes</td>
+ <td>ruiglopes at yahoo dot com</td>
+ <td>1.3.3</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Romanian</td>
+ <td>Ionut Dumitrascu<br/>Alexandru Iosup</td>
+ <td>reddumy at yahoo dot com<br/>aiosup at yahoo dot com</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Russian</td>
+ <td>Alexandr Chelpanov</td>
+ <td>cav at cryptopro dot ru</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Serbian</td>
+ <td>Dejan Milosavljevic</td>
+ <td>dmilos at email dot com</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>SerbianCyrilic</td>
+ <td>Nedeljko Stefanovic</td>
+ <td>stenedjo at yahoo dot com</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Slovak</td>
+ <td>Stanislav Kudláč</td>
+ <td>skudlac at pobox dot sk</td>
+ <td>1.2.18</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Slovene</td>
+ <td>Matjaž Ostroveršnik</td>
+ <td>matjaz.ostroversnik at ostri dot org</td>
+ <td>1.4.6</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Spanish</td>
+ <td>Bartomeu<br/>Francisco Oltra Thennet<br/>David Vaquero</td>
+ <td>bartomeu at loteria3cornella dot com<br/>foltra at puc dot cl<br/>david at grupoikusnet dot com</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Swedish</td>
+ <td>Mikael Hallin</td>
+ <td>mikaelhallin at yahoo dot se</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Turkish</td>
+ <td>Emin Ilker Cetinbas</td>
+ <td>niw3 at yahoo dot com</td>
+ <td>1.6.0</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Ukrainian</td>
+ <td>Olexij Tkatchenko</td>
+ <td>olexij.tkatchenko at parcs dot de</td>
+ <td>1.4.1</td>
+ </tr>
+ <tr bgcolor="#ffffff">
+ <td>Vietnamese</td>
+ <td>Dang Minh Tuan</td>
+ <td>tuanvietkey at gmail dot com</td>
+ <td>1.6.0</td>
+ </tr>
+ <!-- table content end -->
+ </table>
+</td>
+</tr>
+</table>
+\endhtmlonly
+
+
+\latexonly
+\begin{tabular}{|l|l|l|l|}
+ \hline
+ {\bf Language} & {\bf Maintainer} & {\bf Contact address} & {\bf Status} \\
+ \hline
+
+ \hline
+ Afrikaans & Johan Prinsloo & {\tt\tiny johan@zippysnoek.com} & 1.6.0 \\
+ \hline
+ Arabic & Moaz Reyad & {\tt\tiny moazreyad@yahoo.com} & 1.4.6 \\
+ \hline
+ Brazilian Portuguese & Fabio "FJTC" Jun Takada Chino & {\tt\tiny jun-chino@uol.com.br} & up-to-date \\
+ \hline
+ Catalan & Maximiliano Pin & {\tt\tiny max.pin@bitroit.com} & 1.6.0 \\
+ ~ & Albert Mora & {\tt\tiny amora@iua.upf.es} & ~ \\
+ \hline
+ Chinese & Li Daobing & {\tt\tiny lidaobing@gmail.com} & 1.6.0 \\
+ ~ & Wei Liu & {\tt\tiny liuwei@asiainfo.com} & ~ \\
+ \hline
+ Chinese Traditional & Daniel YC Lin & {\tt\tiny dlin.tw@gmail.com} & 1.6.0 \\
+ ~ & Gary Lee & {\tt\tiny garywlee@gmail.com} & ~ \\
+ \hline
+ Croatian & Boris Bralo & {\tt\tiny boris.bralo@zg.htnet.hr} & 1.6.0 \\
+ \hline
+ Czech & Petr P\v{r}ikryl & {\tt\tiny prikrylp@skil.cz} & up-to-date \\
+ \hline
+ Danish & Erik S\o{}e S\o{}rensen & {\tt\tiny eriksoe+doxygen@daimi.au.dk} & 1.5.4 \\
+ \hline
+ Dutch & Dimitri van Heesch & {\tt\tiny dimitri@stack.nl} & up-to-date \\
+ \hline
+ English & Dimitri van Heesch & {\tt\tiny dimitri@stack.nl} & up-to-date \\
+ \hline
+ Esperanto & Ander Martinez & {\tt\tiny dwarfnauko@gmail.com} & 1.6.0 \\
+ \hline
+ Finnish & Antti Laine & {\tt\tiny antti.a.laine@tut.fi} & 1.6.0 \\
+ \hline
+ French & Xavier Outhier & {\tt\tiny xouthier@yahoo.fr} & up-to-date \\
+ \hline
+ German & Jens Seidel & {\tt\tiny jensseidel@users.sf.net} & 1.6.0 \\
+ \hline
+ Greek & Paul Gessos & {\tt\tiny nickreserved@yahoo.com} & 1.5.4 \\
+ \hline
+ Hungarian & \'{A}kos Kiss & {\tt\tiny akiss@users.sourceforge.net} & 1.4.6 \\
+ ~ & F\"{o}ldv\'{a}ri Gy\"{o}rgy & {\tt\tiny foldvari lost@cyberspace} & ~ \\
+ \hline
+ Indonesian & Hendy Irawan & {\tt\tiny ceefour@gauldong.net} & 1.4.6 \\
+ \hline
+ Italian & Alessandro Falappa & {\tt\tiny alessandro@falappa.net} & 1.6.0 \\
+ ~ & Ahmed Aldo Faisal & {\tt\tiny aaf23@cam.ac.uk} & ~ \\
+ \hline
+ Japanese & Hiroki Iseri & {\tt\tiny goyoki@gmail.com} & 1.6.0 \\
+ ~ & Ryunosuke Satoh & {\tt\tiny sun594@hotmail.com} & ~ \\
+ ~ & Kenji Nagamatsu & {\tt\tiny naga@joyful.club.ne.jp} & ~ \\
+ ~ & Iwasa Kazmi & {\tt\tiny iwasa@cosmo-system.jp} & ~ \\
+ \hline
+ JapaneseEn & see the Japanese language & {\tt\tiny ~} & English based \\
+ \hline
+ Korean & Kim Taedong & {\tt\tiny fly1004@gmail.com} & up-to-date \\
+ ~ & SooYoung Jung & {\tt\tiny jung5000@gmail.com} & ~ \\
+ ~ & Richard Kim & {\tt\tiny ryk@dspwiz.com} & ~ \\
+ \hline
+ KoreanEn & see the Korean language & {\tt\tiny ~} & English based \\
+ \hline
+ Lithuanian & Tomas Simonaitis & {\tt\tiny haden@homelan.lt} & 1.4.6 \\
+ ~ & Mindaugas Radzius & {\tt\tiny mindaugasradzius@takas.lt} & ~ \\
+ ~ & Aidas Berukstis & {\tt\tiny aidasber@takas.lt} & ~ \\
+ \hline
+ Macedonian & Slave Jovanovski & {\tt\tiny slavejovanovski@yahoo.com} & 1.6.0 \\
+ \hline
+ Norwegian & Lars Erik Jordet & {\tt\tiny lejordet@gmail.com} & 1.4.6 \\
+ \hline
+ Persian & Ali Nadalizadeh & {\tt\tiny nadalizadeh@gmail.com} & 1.6.0 \\
+ \hline
+ Polish & Piotr Kaminski & {\tt\tiny Piotr.Kaminski@ctm.gdynia.pl} & up-to-date \\
+ ~ & Grzegorz Kowal & {\tt\tiny g\_kowal@poczta.onet.pl} & ~ \\
+ ~ & Krzysztof Kral & {\tt\tiny krzysztof.kral@gmail.com} & ~ \\
+ \hline
+ Portuguese & Rui Godinho Lopes & {\tt\tiny ruiglopes@yahoo.com} & 1.3.3 \\
+ \hline
+ Romanian & Ionut Dumitrascu & {\tt\tiny reddumy@yahoo.com} & 1.6.0 \\
+ ~ & Alexandru Iosup & {\tt\tiny aiosup@yahoo.com} & ~ \\
+ \hline
+ Russian & Alexandr Chelpanov & {\tt\tiny cav@cryptopro.ru} & 1.6.0 \\
+ \hline
+ Serbian & Dejan Milosavljevic & {\tt\tiny dmilos@email.com} & 1.6.0 \\
+ \hline
+ SerbianCyrilic & Nedeljko Stefanovic & {\tt\tiny stenedjo@yahoo.com} & 1.6.0 \\
+ \hline
+ Slovak & Stanislav Kudl\'{a}\v{c} & {\tt\tiny skudlac@pobox.sk} & 1.2.18 \\
+ \hline
+ Slovene & Matja\v{z} Ostrover\v{s}nik & {\tt\tiny matjaz.ostroversnik@ostri.org} & 1.4.6 \\
+ \hline
+ Spanish & Bartomeu & {\tt\tiny bartomeu@loteria3cornella.com} & 1.6.0 \\
+ ~ & Francisco Oltra Thennet & {\tt\tiny foltra@puc.cl} & ~ \\
+ ~ & David Vaquero & {\tt\tiny david@grupoikusnet.com} & ~ \\
+ \hline
+ Swedish & Mikael Hallin & {\tt\tiny mikaelhallin@yahoo.se} & 1.6.0 \\
+ \hline
+ Turkish & Emin Ilker Cetinbas & {\tt\tiny niw3@yahoo.com} & 1.6.0 \\
+ \hline
+ Ukrainian & Olexij Tkatchenko & {\tt\tiny olexij.tkatchenko@parcs.de} & 1.4.1 \\
+ \hline
+ Vietnamese & Dang Minh Tuan & {\tt\tiny tuanvietkey@gmail.com} & 1.6.0 \\
+ \hline
+\end{tabular}
+\endlatexonly
+
+
+Most people on the list have indicated that they were also busy
+doing other things, so if you want to help to speed things up please
+let them (or me) know.
+
+If you want to add support for a language that is not yet listed
+please read the next section.
+
+
+<h3>Adding a new language to doxygen</h3>
+
+This short HOWTO explains how to add support for the new language to Doxygen:
+
+Just follow these steps:
+<ol>
+<li>Tell me for which language you want to add support. If no one else
+ is already working on support for that language, you will be
+ assigned as the maintainer for the language.
+<li>Create a copy of translator_en.h and name it
+ translator_\<your_2_letter_country_code\>.h
+ I'll use xx in the rest of this document.
+<li>Add definition of the symbol for your language in the configure
+at two places in the script:
+ <ol>
+ <li>After the <code>f_langs=</code> is statement, in lower case.
+ <li>In the string that following <code>\@allowed=</code> in upper case.
+ </ol>
+The rerun the configure script such that is generates src/lang_cfg.h.
+This file should now contain a \#define for your language code.
+<li>Edit language.cpp:
+ Add a
+\verbatim
+#ifdef LANG_xx
+#include<translator_xx.h>
+#endif
+\endverbatim
+ Remember to use the same symbol LANG_xx that you added to \c lang_cfg.h.
+ I.e., the \c xx should be capital letters that identify your language.
+ On the other hand, the \c xx inside your \c translator_xx.h should use
+ lower case.
+ <p>Now, in <code>setTranslator()</code> add
+\verbatim
+#ifdef LANG_xx
+ else if (L_EQUAL("your_language_name"))
+ {
+ theTranslator = new TranslatorYourLanguage;
+ }
+#endif
+\endverbatim
+ after the <code>if { ... }</code>. I.e., it must be placed after the code
+ for creating the English translator at the beginning, and before the
+ <code>else { ... }</code> part that creates the translator for the
+ default language (English again).
+<li>Edit libdoxygen.pro.in and add \c translator_xx.h to
+ the \c HEADERS line.
+<li>Edit <code>translator_xx.h</code>:
+ <ul>
+ <li>Rename <code>TRANSLATOR_EN_H</code> to <code>TRANSLATOR_XX_H</code>
+ twice (i.e. in the \c \#ifndef and \c \#define preprocessor commands at
+ the beginning of the file).
+ <li>Rename TranslatorEnglish to TranslatorYourLanguage
+ <li>In the member <code>idLanguage()</code> change "english" into the
+ name of your language (use lower case characters only). Depending
+ on the language you may also wish to change the member functions
+ latexLanguageSupportCommand(), idLanguageCharset() and others
+ (you will recognize them when you start the work).
+ <li>Edit all the strings that are returned by the member functions that
+ start with tr.
+ Try to match punctuation and capitals!
+ To enter special characters (with accents) you can:
+ <ul>
+ <li> Enter them directly if your keyboard supports that and you are
+ using a Latin-1 font. Doxygen will translate the
+ characters to proper \f$\mbox{\LaTeX}\f$ and leave the
+ HTML and man output for what it is (which is fine, if
+ idLanguageCharset() is set correctly).
+ <li> Use html codes like \ä for an a with an umlaut (i.e. ä).
+ See the HTML specification for the codes.
+ </ul>
+ </ul>
+<li>Run configure and make again from the root of the distribution,
+ in order to regenerated the Makefiles.
+<li>Now you can use <code>OUTPUT_LANGUAGE = your_language_name</code>
+ in the config file to generate output in your language.
+<li>Send <code>translator_xx.h</code> to me so I can add it to doxygen.
+ Send also your name and e-mail address to be included in the
+ \c maintainers.txt list.
+</ol>
+
+
+<h3>Maintaining a language</h3>
+
+New versions of doxygen may use new translated sentences. In such
+situation, the \c Translator class requires implementation of new
+methods -- its interface changes. Of course, the English
+sentences need to be translated to the other languages. At least,
+new methods have to be implemented by the language-related
+translator class; otherwise, doxygen wouldn't even compile. Waiting
+until all language maintainers have translated the new sentences and
+sent the results would not be very practical. The following text
+describes the usage of translator adapters to solve the problem.
+
+<b>The role of Translator Adapters.</b>
+Whenever the \c Translator class interface changes in the new
+release, the new class \c TranslatorAdapter_x_y_z is added to the \c
+translator_adapter.h file (here x, y, and z are numbers that
+correspond to the current official version of doxygen). All
+translators that previously derived from the \c Translator class now
+derive from this adapter class.
+
+The \c TranslatorAdapter_x_y_z class implements the new, required
+methods. If the new method replaces some similar but obsolete
+method(s) (e.g. if the number of arguments changed and/or the
+functionality of the older method was changed or enriched), the \c
+TranslatorAdapter_x_y_z class may use the obsolete method to get the
+result which is as close as possible to the older result in the
+target language. If it is not possible, the result (the default
+translation) is obtained using the English translator, which is (by
+definition) always up-to-date.
+
+<b>For example,</b> when the new \c trFile() method with
+parameters (to determine the capitalization of the first letter and
+the singular/plural form) was introduced to replace the older method
+\c trFiles() without arguments, the following code appeared in one
+of the translator adapter classes:
+
+\verbatim
+ /*! This is the default implementation of the obsolete method
+ * used in the documentation of a group before the list of
+ * links to documented files. This is possibly localized.
+ */
+ virtual QCString trFiles()
+ { return "Files"; }
+
+ /*! This is the localized implementation of newer equivalent
+ * using the obsolete method trFiles().
+ */
+ virtual QCString trFile(bool first_capital, bool singular)
+ {
+ if (first_capital && !singular)
+ return trFiles(); // possibly localized, obsolete method
+ else
+ return english.trFile(first_capital, singular);
+ }
+\endverbatim
+
+The \c trFiles() is not present in the \c TranslatorEnglish class,
+because it was removed as obsolete. However, it was used until now
+and its call was replaced by
+
+\verbatim
+ trFile(true, false)
+\endverbatim
+
+in the doxygen source files. Probably, many language translators
+implemented the obsolete method, so it perfectly makes sense to use
+the same language dependent result in those cases. The \c
+TranslatorEnglish does not implement the old method. It derives
+from the abstract \c Translator class. On the other hand, the old
+translator for a different language does not implement the new \c
+trFile() method. Because of that it is derived from another base
+class -- \c TranslatorAdapter_x_y_z. The \c TranslatorAdapter_x_y_z
+class have to implement the new, required \c trFile() method.
+However, the translator adapter would not be compiled if the \c
+trFiles() method was not implemented. This is the reason for
+implementing the old method in the translator adapter class (using
+the same code, that was removed from the TranslatorEnglish).
+
+The simplest way would be to pass the arguments to the English
+translator and to return its result. Instead, the adapter uses the
+old \c trFiles() in one special case -- when the new
+<code>trFile(true, false)</code> is called. This is the
+mostly used case at the time of introducing the new method -- see
+above. While this may look too complicated, the technique allows
+the developers of the core sources to change the Translator
+interface, while the users may not even notice the change. Of
+course, when the new \c trFile() is used with different arguments,
+the English result is returned and it will be noticed by non English
+users. Here the maintainer of the language translator should
+implement at least that one particular method.
+
+<b>What says the base class of a language translator?</b>
+If the language translator class inherits from any adapter class the
+maintenance is needed. In such case, the language translator is not
+considered up-to-date. On the other hand, if the language
+translator derives directly from the abstract class \c Translator, the
+language translator is up-to-date.
+
+The translator adapter classes are chained so that the older
+translator adapter class uses the one-step-newer translator adapter
+as the base class. The newer adapter does less \e adapting work
+than the older one. The oldest adapter class derives (indirectly)
+from all of the adapter classes. The name of the adapter class is
+chosen so that its suffix is derived from the previous official
+version of doxygen that did not need the adapter. This way, one can
+say approximately, when the language translator class was last
+updated -- see details below.
+
+The newest translator adapter derives from the abstract \c
+TranslatorAdapterBase class that derives directly from the abstract
+\c Translator class. It adds only the private English-translator
+member for easy implementation of the default translation inside the
+adapter classes, and it also enforces implementation of one method
+for noticing the user that the language translation is not up-to-date
+(because of that some sentences in the generated files may appear in
+English).
+
+Once the oldest adapter class is not used by any of the language
+translators, it can be removed from the doxygen project. The
+maintainers should try to reach the state with the minimal number of
+translator adapter classes.
+
+<b>To simplify the maintenance of the language translator classes</b>
+for the supported languages, the \c translator.py Python
+script was developed (located in \c doxygen/doc directory).
+It extracts the important information about obsolete and
+new methods from the source files for each of the languages.
+The information is stored in the <em>translator report</em> ASCII file
+(translator_report.txt).
+
+\htmlonly If you compiled this documentation
+from sources and if you have also doxygen sources available the
+link <a href="../doc/translator_report.txt"
+><code>doxygen/doc/translator_report.txt</code></a> should be valid.\endhtmlonly
+
+Looking at the base class of the language translator, the script
+guesses also the status of the translator -- see the last column of
+the table with languages above. The \c translator.py is called
+automatically when the doxygen documentation is generated. You can
+also run the script manualy whenever you feel that it can help you.
+Of course, you are not forced to use the results of the script. You
+can find the same information by looking at the adapter class and
+its base classes.
+
+<b>How should I update my language translator?</b> Firstly, you
+should be the language maintainer, or you should let him/her know
+about the changes. The following text was written for the language
+maintainers as the primary audience.
+
+There are several approaches to be taken when updating your
+language. If you are not extremely busy, you should always chose
+the most radical one. When the update takes much more time than you
+expected, you can always decide use some suitable translator adapter to
+finish the changes later and still make your translator working.
+
+<b>The most radical way of updating the language translator</b> is
+to make your translator class derive directly
+from the abstract class \c Translator and provide translations for the
+methods that are required to be implemented -- the compiler will
+tell you if you forgot to implement some of them. If you are in
+doubt, have a look at the \c TranslatorEnglish class to recognize the
+purpose of the implemented method. Looking at the previously used
+adapter class may help you sometimes, but it can also be misleading
+because the adapter classes do implement also the obsolete methods
+(see the previous \c trFiles() example).
+
+In other words, the up-to-date language translators do not need the
+\c TranslatorAdapter_x_y_z classes at all, and you do not need to
+implement anything else than the methods required by the Translator
+class (i.e. the pure virtual methods of the \c Translator -- they
+end with <code>=0;</code>).
+
+If everything compiles fine, try to run \c translator.py, and have a
+look at the translator report (ASCII file) at the \c doxygen/doc
+directory. Even if your translator is marked as up-to-date, there
+still may be some remarks related to your souce code. Namely, the
+obsolete methods--that are not used at all--may be listed in the
+section for your language. Simply, remove their code (and run the \c
+translator.py again). Also, you will be informed when you forgot to
+change the base class of your translator class to some newer adapter
+class or directly to the Translator class.
+
+<b>If you do not have time to finish all the updates</b> you should
+still start with <em>the most radical approach</em> as described
+above. You can always change the base class to the translator
+adapter class that implements all of the not-yet-implemented methods.
+
+<b>If you prefer to update your translator gradually</b>, have a look
+at \c TranslatorEnglish (the \c translator_en.h file). Inside, you
+will find the comments like <code>new since 1.2.4</code> that separate
+always a number of methods that were implemented in the stated
+version. Do implement the group of methods that are placed below the
+comment that uses the same version numbers as your translator adapter
+class. (For example, your translator class have to use the \c
+TranslatorAdapter_1_2_4, if it does not implement the methods below
+the comment <code>new since 1.2.4</code>. When you implement them,
+your class should use newer translator adapter.
+
+Run the \c translator.py script occasionaly and give it your \c xx
+identification (from \c translator_xx.h) to create the translator
+report shorter (also produced faster) -- it will contain only the
+information related to your translator. Once you reach the state when
+the base class should be changed to some newer adapter, you will see
+the note in the translator report.
+
+Warning: Don't forget to compile Doxygen to discover, whether it is
+compilable. The \c translator.py does not check if everything is
+correct with respect to the compiler. Because of that, it may lie
+sometimes about the necessary base class.
+
+<b>The most obsolete language translators</b> would lead to
+implementation of too complicated adapters. Because of that, doxygen
+developers may decide to derive such translators from the \c
+TranslatorEnglish class, which is by definition always up-to-date.
+
+When doing so, all the missing methods will be replaced by the
+English translation. This means that not-implemented methods will
+always return the English result. Such translators are marked using
+word \c obsolete. You should read it <b>really obsolete</b>. No
+guess about the last update can be done.
+
+Often, it is possible to construct better result from the obsolete
+methods. Because of that, the translator adapter classes should be
+used if possible. On the other hand, implementation of adapters for
+really obsolete translators brings too much maintenance and
+run-time overhead.
+
+*/
+