Commit 5fdcd960 authored by albert-github's avatar albert-github
Browse files

Consistency in language part of the documentation 

Made documentation more inline with other parts of the documentation (regarding the way e.g. filenames are presented)
Corrected some spelling errors
Corrected the warning in the language.doc by placing ta reference to the files from which language.doc is generated
Corrected the color for the languages that are still v1.4.6 (language name now also red  in stead of a pink background, was confusing with languages that were 1.5 / 1.6 compatible)
parent ef7c0d69

doc/language.doc

+36 −34
Original line number Diff line number Diff line 
/******************************************************************************

 * Do not edit this file. It was generated by the translator.py script.

 * Instead edit language.tpl and maintainers.txt

 *

 * Copyright (C) 1997-2013 by Dimitri van Heesch.

 *
@@ -9,7 +10,7 @@ 
 * 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

 * Documents produced by doxygen are derivative works derived from the

 * input used in their production; they are not affected by this license.

 *

 */
@@ -20,6 +21,7 @@ 
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 option \ref cfg_output_language "OUTPUT_LANGUAGE" in the 

configuration file (with default name and known as Doxyfile).



Currently (version 1.8.5), 40 languages
@@ -58,7 +60,7 @@ when the translator was updated. 
    <td bgcolor="#ffcccc">1.6.0</td>

  </tr>

  <tr bgcolor="#ffffff">

    <td bgcolor="#ffcccc">Arabic</td>

    <td bgcolor="#ff5555">Arabic</td>

    <td>Moaz Reyad<br/>Muhammad Bashir Al-Noimi</td>

    <td><span style="color: brown">[resigned]</span><br/>mbnoimi at gmail dot com</td>

    <td bgcolor="#ff5555">1.4.6</td>
@@ -154,7 +156,7 @@ when the translator was updated. 
    <td bgcolor="#ffffcc">1.8.4</td>

  </tr>

  <tr bgcolor="#ffffff">

    <td bgcolor="#ffcccc">Hungarian</td>

    <td bgcolor="#ff5555">Hungarian</td>

    <td>Ákos Kiss<br/>Földvári György</td>

    <td>akiss at users dot sourceforge dot net<br/><span style="color: brown">[unreachable]</span></td>

    <td bgcolor="#ff5555">1.4.6</td>
@@ -202,7 +204,7 @@ when the translator was updated. 
    <td bgcolor="#ccffcc">up-to-date</td>

  </tr>

  <tr bgcolor="#ffffff">

    <td bgcolor="#ffcccc">Lithuanian</td>

    <td bgcolor="#ff5555">Lithuanian</td>

    <td>Tomas Simonaitis<br/>Mindaugas Radzius<br/>Aidas Berukstis<br/><span style="color: red; background-color: yellow">-- searching for the maintainer --</span></td>

    <td><span style="color: brown">[unreachable]</span><br/><span style="color: brown">[unreachable]</span><br/><span style="color: brown">[unreachable]</span><br/><span style="color: brown">[Please, try to help to find someone.]</span></td>

    <td bgcolor="#ff5555">1.4.6</td>
@@ -214,7 +216,7 @@ when the translator was updated. 
    <td bgcolor="#ffcccc">1.6.0</td>

  </tr>

  <tr bgcolor="#ffffff">

    <td bgcolor="#ffcccc">Norwegian</td>

    <td bgcolor="#ff5555">Norwegian</td>

    <td>Lars Erik Jordet</td>

    <td>lejordet at gmail dot com</td>

    <td bgcolor="#ff5555">1.4.6</td>
@@ -268,7 +270,7 @@ when the translator was updated. 
    <td bgcolor="#ccffcc">up-to-date</td>

  </tr>

  <tr bgcolor="#ffffff">

    <td bgcolor="#ffcccc">Slovene</td>

    <td bgcolor="#ff5555">Slovene</td>

    <td>Matjaž Ostroveršnik</td>

    <td>matjaz dot ostroversnik at ostri dot org</td>

    <td bgcolor="#ff5555">1.4.6</td>
@@ -447,32 +449,32 @@ 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:

This short HOWTO explains how to add support for the new language to doxygen:



Just follow these steps:

Just follow the following 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:

<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`

script 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

The rerun the `configure` script such that is generates `doxygen/src/lang_cfg.h`.

This file should now contain a  \c \#define for your language code.

<li>Edit `doxygen/src/language.cpp`:

    Add the following code:

\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.

    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.
@@ -489,7 +491,7 @@ This file should now contain a \#define for your language 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

<li>Edit `doxygen/src/libdoxygen.pro.in` and add \c translator_xx.h to

    the \c HEADERS line.

<li>Edit <code>translator_xx.h</code>:

   <ul>
@@ -497,11 +499,11 @@ This file should now contain a \#define for your language code. 
   <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>Rename \c TranslatorEnglish to \c 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() and other (you will recognize them when

     `latexLanguageSupportCommand()` and other (you will recognize them when

     you start the work).

   <li>Edit all the strings that are returned by the member functions that

     start with \c tr.
@@ -512,17 +514,17 @@ This file should now contain a \#define for your language code. 
           the text is expected to be saved using the UTF-8 encoding. Doxygen

           will translate the characters to proper \f$\mbox{\LaTeX}\f$ and

           leaves the HTML and man output in UTF-8.

     <li>  Use html codes like \&auml; for an a with an umlaut (i.e. &auml;).

     <li>  Use HTML codes like \&auml; for an \c a with an \c umlaut (i.e. &auml;).

           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>Run \c configure and \c make again from the root (i.e. in the \c doxygen

    directory) of the distribution, in order to regenerate the \c 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. You can also clone the Doxygen repository

    \c maintainers.txt list. You can also clone the doxygen repository

    at GitHub and make a PullRequest later.

</ol>
@@ -599,7 +601,7 @@ 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.

class has 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
@@ -619,9 +621,9 @@ 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

If the language translator class inherits from any adapter class then

maintenance is needed.  In such case, the language translator is

considered not 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.
@@ -640,7 +642,7 @@ 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

for notifying the user that the language translation is not up-to-date

(because of that some sentences in the generated files may appear in

English).
@@ -671,7 +673,7 @@ 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

<b>How should I update my language translator?</b> First, 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.
@@ -725,7 +727,7 @@ 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.

your class should use a newer translator adapter.



Run the \c translator.py script occasionally and give it your \c xx

identification (from \c translator_xx.h) to create the translator
@@ -734,7 +736,7 @@ 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

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.
@@ -747,7 +749,7 @@ 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

the 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

doc/language.tpl

+30 −29
Original line number Diff line number Diff line
@@ -13,7 +13,7 @@ change the language.doc, make the changes here and inside maintainers.txt. 
 * 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

 * Documents produced by doxygen are derivative works derived from the

 * input used in their production; they are not affected by this license.

 *

 */
@@ -24,6 +24,7 @@ change the language.doc, make the changes here and inside maintainers.txt. 
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 option \ref cfg_output_language "OUTPUT_LANGUAGE" in the 

configuration file (with default name and known as Doxyfile).



Currently (version %(doxVersion)s), %(numLangStr)s languages
@@ -47,32 +48,32 @@ 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:

This short HOWTO explains how to add support for the new language to doxygen:



Just follow these steps:

Just follow the following 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:

<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`

script 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

The rerun the `configure` script such that is generates `doxygen/src/lang_cfg.h`.

This file should now contain a  \c \#define for your language code.

<li>Edit `doxygen/src/language.cpp`:

    Add the following code:

\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.

    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.
@@ -89,7 +90,7 @@ This file should now contain a \#define for your language 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

<li>Edit `doxygen/src/libdoxygen.pro.in` and add \c translator_xx.h to

    the \c HEADERS line.

<li>Edit <code>translator_xx.h</code>:

   <ul>
@@ -97,11 +98,11 @@ This file should now contain a \#define for your language code. 
   <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>Rename \c TranslatorEnglish to \c 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() and other (you will recognize them when

     `latexLanguageSupportCommand()` and other (you will recognize them when

     you start the work).

   <li>Edit all the strings that are returned by the member functions that

     start with \c tr.
@@ -112,17 +113,17 @@ This file should now contain a \#define for your language code. 
           the text is expected to be saved using the UTF-8 encoding. Doxygen

           will translate the characters to proper \f$\mbox{\LaTeX}\f$ and

           leaves the HTML and man output in UTF-8.

     <li>  Use html codes like \&auml; for an a with an umlaut (i.e. &auml;).

     <li>  Use HTML codes like \&auml; for an \c a with an \c umlaut (i.e. &auml;).

           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>Run \c configure and \c make again from the root (i.e. in the \c doxygen

    directory) of the distribution, in order to regenerate the \c 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. You can also clone the Doxygen repository

    \c maintainers.txt list. You can also clone the doxygen repository

    at GitHub and make a PullRequest later.

</ol>
@@ -199,7 +200,7 @@ 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.

class has 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
@@ -219,9 +220,9 @@ 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

If the language translator class inherits from any adapter class then

maintenance is needed.  In such case, the language translator is

considered not 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.
@@ -240,7 +241,7 @@ 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

for notifying the user that the language translation is not up-to-date

(because of that some sentences in the generated files may appear in

English).
@@ -270,7 +271,7 @@ 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

<b>How should I update my language translator?</b> First, 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.
@@ -324,7 +325,7 @@ 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.

your class should use a newer translator adapter.



Run the \c translator.py script occasionally and give it your \c xx

identification (from \c translator_xx.h) to create the translator
@@ -333,7 +334,7 @@ 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

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.
@@ -346,7 +347,7 @@ 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

the 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

doc/translator.py

+2 −2
Original line number Diff line number Diff line
@@ -1829,7 +1829,7 @@ class TrManager: 
        # document template.

        tplDic = {}



        s = u'Do not edit this file. It was generated by the %s script.' % self.script_name

        s = u'Do not edit this file. It was generated by the %s script.\n * Instead edit %s and %s' % (self.script_name, self.languageTplFileName, self.maintainersFileName)

        tplDic['editnote'] = s



        tplDic['doxVersion'] = self.doxVersion
@@ -1879,7 +1879,7 @@ class TrManager: 
            # translator are colour marked in the language columnt. Less

            # "heavy" color is used (when compared with the Status column).

            if obj.readableStatus.startswith('1.4'):

                bkcolor = self.getBgcolorByReadableStatus('1.6')

                bkcolor = self.getBgcolorByReadableStatus('1.4')

            else:

                bkcolor = '#ffffff'