Release-1.3.6-20040222

1 files changed, 54 insertions, 51 deletions

diff --git a/doc/language.tpl b/doc/language.tpl
index f33a256..d8cc0d3 100644
--- a/doc/language.tpl
+++ b/doc/language.tpl
@@ -1,7 +1,9 @@
+
+ATTENTION! This is the template for generating language.doc. If you want to
+change the language.doc, make the changes here and inside maintainers.txt.
+
 /******************************************************************************
- * <notice>This is the template for generating language.doc.  
- * Edit manually this file, not the language.doc!</notice>
- * 
+ * %(editnote)s 
  *
  * Copyright (C) 1997-2004 by Dimitri van Heesch.
  *
@@ -14,25 +16,27 @@
  * Documents produced by Doxygen are derivative works derived from the
  * input used in their production; they are not affected by this license.
  *
+ * $Id$
  */
 /*! \page langhowto Internationalization
 
 <h3>Support for multiple languages</h3>
 
-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.
+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 $version), $numlang languages 
-are supported (sorted alphabetically): 
-$languages.
+Currently (version %(doxVersion)s), %(numLangStr)s languages 
+are supported (sorted alphabetically):
+%(supportedLangReadableStr)s.
 
 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.
 
-$information_table
+%(informationTable)s
 
 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 
@@ -44,7 +48,7 @@ please read the next section.
 
 <h3>Adding a new language to doxygen</h3>
 
-This short HOWTO explains how to add support for a new language to Doxygen:
+This short HOWTO explains how to add support for the new language to Doxygen:
 
 Just follow these steps:
 <ol>
@@ -73,7 +77,7 @@ Just follow these steps:
 \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 be
+    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
@@ -248,18 +252,18 @@ 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
+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_file_name). \htmlonly If you compiled this documentation
+(%(translatorReportFileName)s). \htmlonly If you compiled this documentation
 from sources and if you have also doxygen sources available the
-link $translator_report_link should be valid.\endhtmlonly 
+link %(translatorReportLink)s 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.pl is called
+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
@@ -294,49 +298,48 @@ 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.pl, and have a
+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
+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).
+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>, 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.
-
-Probably the easiest approach of the gradual update is to look at
-the translator report to the part where the list of the implemented
-translator adapters is shown. Then:
- - Look how many required methods each adapter implements and guess
-   how many methods you are willing to update (to spend the time
-   with).  
- - Choose the related oldest translator adapters to be removed (i.e.
-   not used by your translator).
- - Change the base class of your translator class to the translator
-   adapter that you want to use.
- - Implement the methods that were implemented by the older translator
-   adapters.
-
-Notice: 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 from some newer adapter
-on.  Focus on the methods listed as \e required.
-
-<b>The really obsolete language translators</b> may lead to too much
-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.
+<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