From 5fdcd960334a7c12de937208f5e03824c3e33dea Mon Sep 17 00:00:00 2001 From: albert-github Date: Mon, 16 Sep 2013 18:48:29 +0200 Subject: 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) --- doc/language.doc | 70 ++++++++++++++++++++++++++++--------------------------- doc/language.tpl | 59 +++++++++++++++++++++++----------------------- doc/translator.py | 4 ++-- 3 files changed, 68 insertions(+), 65 deletions(-) diff --git a/doc/language.doc b/doc/language.doc index 8fc8392..c9e0945 100644 --- a/doc/language.doc +++ b/doc/language.doc @@ -1,5 +1,6 @@ /****************************************************************************** * 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. 1.6.0 - Arabic + Arabic Moaz Reyad
Muhammad Bashir Al-Noimi [resigned]
mbnoimi at gmail dot com 1.4.6 @@ -154,7 +156,7 @@ when the translator was updated. 1.8.4 - Hungarian + Hungarian Ákos Kiss
Földvári György akiss at users dot sourceforge dot net
[unreachable] 1.4.6 @@ -202,7 +204,7 @@ when the translator was updated. up-to-date - Lithuanian + Lithuanian Tomas Simonaitis
Mindaugas Radzius
Aidas Berukstis
-- searching for the maintainer -- [unreachable]
[unreachable]
[unreachable]
[Please, try to help to find someone.] 1.4.6 @@ -214,7 +216,7 @@ when the translator was updated. 1.6.0 - Norwegian + Norwegian Lars Erik Jordet lejordet at gmail dot com 1.4.6 @@ -268,7 +270,7 @@ when the translator was updated. up-to-date - Slovene + Slovene Matjaž Ostroveršnik matjaz dot ostroversnik at ostri dot org 1.4.6 @@ -447,32 +449,32 @@ please read the next section.

Adding a new language to doxygen

-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:
  1. 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. -
  2. Create a copy of translator_en.h and name it - translator_\.h - I'll use xx in the rest of this document. -
  3. Add definition of the symbol for your language in the configure -at two places in the script: +
  4. Create a copy of `translator_en.h` and name it + `translator_\.h` + I'll use `xx` in the rest of this document. +
  5. Add definition of the symbol for your language in the `configure` +script at two places in the script:
    1. After the f_langs= is statement, in lower case.
    2. In the string that following \@allowed= in upper case.
    -The rerun the configure script such that is generates src/lang_cfg.h. -This file should now contain a \#define for your language code. -
  6. 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. +
  7. Edit `doxygen/src/language.cpp`: + Add the following code: \verbatim #ifdef LANG_xx #include #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 else { ... } part that creates the translator for the default language (English again). -
  8. Edit libdoxygen.pro.in and add \c translator_xx.h to +
  9. Edit `doxygen/src/libdoxygen.pro.in` and add \c translator_xx.h to the \c HEADERS line.
  10. Edit translator_xx.h:
      @@ -497,11 +499,11 @@ This file should now contain a \#define for your language code.
    • Rename TRANSLATOR_EN_H to TRANSLATOR_XX_H twice (i.e. in the \c \#ifndef and \c \#define preprocessor commands at the beginning of the file). -
    • Rename TranslatorEnglish to TranslatorYourLanguage +
    • Rename \c TranslatorEnglish to \c TranslatorYourLanguage
    • In the member idLanguage() 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).
    • 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. -
    • Use html codes like \ä for an a with an umlaut (i.e. ä). +
    • Use HTML codes like \ä for an \c a with an \c umlaut (i.e. ä). See the HTML specification for the codes.
    -
  11. Run configure and make again from the root of the distribution, - in order to regenerated the Makefiles. +
  12. 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.
  13. Now you can use OUTPUT_LANGUAGE = your_language_name in the config file to generate output in your language.
  14. Send translator_xx.h 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.
@@ -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. What says the base class of a language translator? -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. -How should I update my language translator? Firstly, you +How should I update my language translator? 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 new since 1.2.4. 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 really obsolete. No +the word \c obsolete. You should read it really obsolete. No guess about the last update can be done. Often, it is possible to construct better result from the obsolete diff --git a/doc/language.tpl b/doc/language.tpl index 2b15159..f4b7b41 100644 --- a/doc/language.tpl +++ b/doc/language.tpl @@ -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.

Adding a new language to doxygen

-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:
  1. 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. -
  2. Create a copy of translator_en.h and name it - translator_\.h - I'll use xx in the rest of this document. -
  3. Add definition of the symbol for your language in the configure -at two places in the script: +
  4. Create a copy of `translator_en.h` and name it + `translator_\.h` + I'll use `xx` in the rest of this document. +
  5. Add definition of the symbol for your language in the `configure` +script at two places in the script:
    1. After the f_langs= is statement, in lower case.
    2. In the string that following \@allowed= in upper case.
    -The rerun the configure script such that is generates src/lang_cfg.h. -This file should now contain a \#define for your language code. -
  6. 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. +
  7. Edit `doxygen/src/language.cpp`: + Add the following code: \verbatim #ifdef LANG_xx #include #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 else { ... } part that creates the translator for the default language (English again). -
  8. Edit libdoxygen.pro.in and add \c translator_xx.h to +
  9. Edit `doxygen/src/libdoxygen.pro.in` and add \c translator_xx.h to the \c HEADERS line.
  10. Edit translator_xx.h:
      @@ -97,11 +98,11 @@ This file should now contain a \#define for your language code.
    • Rename TRANSLATOR_EN_H to TRANSLATOR_XX_H twice (i.e. in the \c \#ifndef and \c \#define preprocessor commands at the beginning of the file). -
    • Rename TranslatorEnglish to TranslatorYourLanguage +
    • Rename \c TranslatorEnglish to \c TranslatorYourLanguage
    • In the member idLanguage() 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).
    • 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. -
    • Use html codes like \ä for an a with an umlaut (i.e. ä). +
    • Use HTML codes like \ä for an \c a with an \c umlaut (i.e. ä). See the HTML specification for the codes.
    -
  11. Run configure and make again from the root of the distribution, - in order to regenerated the Makefiles. +
  12. 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.
  13. Now you can use OUTPUT_LANGUAGE = your_language_name in the config file to generate output in your language.
  14. Send translator_xx.h 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.
@@ -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. What says the base class of a language translator? -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. -How should I update my language translator? Firstly, you +How should I update my language translator? 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 new since 1.2.4. 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 really obsolete. No +the word \c obsolete. You should read it really obsolete. No guess about the last update can be done. Often, it is possible to construct better result from the obsolete diff --git a/doc/translator.py b/doc/translator.py index 7e4f012..2e2a200 100644 --- a/doc/translator.py +++ b/doc/translator.py @@ -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' -- cgit v0.12