summaryrefslogtreecommitdiffstats
path: root/doc/language.tpl
diff options
context:
space:
mode:
Diffstat (limited to 'doc/language.tpl')
-rw-r--r--doc/language.tpl221
1 files changed, 195 insertions, 26 deletions
diff --git a/doc/language.tpl b/doc/language.tpl
index 18c0b40..d81c213 100644
--- a/doc/language.tpl
+++ b/doc/language.tpl
@@ -19,16 +19,16 @@
<h3>Support for multiple languages</h3>
-Doxygen has support for multiple languages. This means
-that the text fragments that doxygen generates can changed into languages
-other than English (the default) at configuration time.
+Doxygen has built-in support for multiple languages. This means
+that the text fragments that doxygen generates can be produced in
+languages other than English (the default) at configuration time.
<p>
Currently (version $version), $numlang languages
are supported (sorted alphabetically):
$languages.
The table of information related to the supported languages follows.
-It is sorted by language alphabetically. The <B>Status</B> column
+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.
<p>
@@ -53,7 +53,7 @@ Just follow these steps:
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_counter_code>.h
+ translator_<your_2_letter_country_code>.h
I'll use xx in the rest of this document.
<li>Edit language.cpp:
Add a
@@ -77,7 +77,8 @@ Just follow these steps:
<li>In the member <code>idLanguage()</code> change "english" into the
name of the your language (use lower case characters only). Depending
on the language you may also wish to change the member functions
- latexLanguageSupportCommand() and idLanguageCharset().
+ 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!
@@ -85,7 +86,7 @@ Just follow these steps:
<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 Latex and
+ Doxygen will translate the characters to proper LateX and
leave the Html and man output for what it is (which is fine, if
idLanguageCharset() is set correctly).
<li> Use html codes like \&auml; for an a with an umlaut (i.e. &auml;).
@@ -97,34 +98,202 @@ Just follow these steps:
<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>
-As new versions of doxygen appear, new sentences will be
-added to the Translator interface class. Of course these need to be translated
-as well (otherwise doxygen wouldn't even compile!).
+As new versions of doxygen appear, new sentences (\c trXxxx()
+methods) will be added to the \c Translator interface class. Of
+course, these need to be translated as well (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 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,&nbsp;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 newest adapter class derives
+directly from the abstract class \c Translator.
+
+The name of the adapter class was chosen so that its suffix is
+derived from the previous version of doxygen. This way, one can say
+approximately, when the language translator class was last updated
+-- see details below. The newest adapter translator for CVS release
+(i.e. non official) is named \c TranslatorAdapterCVS. As it derives
+only from the \c Translator class, it can be used only for language
+translator classes that were up-to-date in the time of the last
+release.
+
+Status of the translators that derive from the \c
+TranslatorAdapterCVS is named as <em>almost up-to-date</em>.
+Its code is moved into the new \c Translator_x_y_z when new version
+of doxygen is officially released.
+
+Once the oldest adapter class is not used by any of the language
+translators, it can be removed from the doxygen project. This also
+means, that there probably still is some language which uses the
+oldest adapter. 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.pl perl
+script was developed (located in \c doxygen/doc directory).
+It is able to extract the important information about obsolete and
+new methods from the source files for each of the languages -- see
+the reference to the <em>translator report</em> ASCII file below
+the table of supported languages shown earlier. Looking at the base
+class of the language translator, the script guesses also the status
+of the translator -- see the last column of the mentioned table.
+The \c translator.pl 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).
-Waiting until all language maintainers have translated these new sentences
-and sent the results would not be very practical for me.
+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>).
-Instead, a new class TranslatorAdapter_x_y_z will be added to
-translator_adapter.h (here x,y, and z correspond to the current
-version of doxygen). And all translators that previous derived from
-Translator will now derive from this adapter class.
+If everything compiles fine, try to run \c translator.pl, 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.pl again).
-The Adapter class contains the new sentences with
-default translations using the English translator (which is always up to date).
-Instead of deriving your TranslatorXX class directly from Translator it will
-derive from the intermediate class TranslatorAdapter_x_y_z.
+<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.
-Thus, if a translator class inherits from a adapter class
-maintenance is needed. By looking at the adapter class itself (and its base
-classes) you can easily see which methods need to be updated.
+<b>If you prefer to update your translator gradually</b>, look
+at the <em>translator report</em> generated by the \c translator.pl script
+and choose one of the missing method that is implemented by the
+translator adapter, that is used as your base class. When there is
+not such a method in your translator adapter base class, you probably
+can change the translator adapter base to the newer one.
-To update a language simply make your translator class derive from
-the abstract class Translator and provide translations for the methods that
-were previously provided by the adapter class (and its base classes).
+Do not blindly implement all methods that are implemented by your
+translator adapter base class. The reason is that the adapter
+classes implement also obsolete methods. Another reason is that
+some of the methods could become obsolete later.
*/