Merge pull request #40 from albert-github/feature/language

Consistency in language part of the documentation

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

@@ -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'