Release-1.2.8-20010715

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.
 
 */