[gtksourceview/wip/docs] docs: update wrt translatable strings in *.lang files

[Sébastien Wilmet <swilmet src gnome org>]

commit 9a51dcdec18570bcdde6971461329570e21412fa
Author: Sébastien Wilmet <swilmet gnome org>
Date:   Sun Sep 17 15:25:28 2017 +0200

    docs: update wrt translatable strings in *.lang files

 docs/reference/lang-reference.xml.in |   33 +++++++++++++++++++++------------
 1 files changed, 21 insertions(+), 12 deletions(-)
---
diff --git a/docs/reference/lang-reference.xml.in b/docs/reference/lang-reference.xml.in
index 0893702..6ee1911 100644
--- a/docs/reference/lang-reference.xml.in
+++ b/docs/reference/lang-reference.xml.in
@@ -162,12 +162,21 @@ underscores ("<code>_</code>").
 </varlistentry>
 
 <varlistentry>
-<term><code>name</code> (mandatory)</term>
-<listitem><para>
-The translatable name of the language presented to the user.
-It can be marked for translation putting an underscore before the attribute
-name (see the gettext documentation).
-</para></listitem>
+<term><code>name</code> or <code>_name</code> (mandatory)</term>
+<listitem>
+  <para>
+    The name of the language presented to the user. With <code>_name</code>, the
+    string is marked for translation (see the gettext documentation).
+  </para>
+
+  <para>
+    The name should be marked for translation only if: (1) it contains a common
+    English word, for example "C++ header" should be translated, but not "C++"
+    or "XML". Or (2) if the name contains several words, because in some
+    languages the word order should be different, for example "LLVM IR" or "RPM
+    spec" should be marked for translation.
+  </para>
+</listitem>
 </varlistentry>
 
 <varlistentry>
@@ -178,13 +187,13 @@ The version of the XML format (currently "2.0").
 </varlistentry>
 
 <varlistentry>
-<term><code>section</code> (optional)</term>
+<term><code>section</code> or <code>_section</code> (optional)</term>
 <listitem><para>
-The translatable category in which the language has to be grouped when
-presented to the user. It can be marked for translation putting
-an underscore before the attribute name. Currently used categories in
-GtkSourceView are "Source", "Script",  "Markup" and "Other", but
-it is possible to use arbitrary categories (while usually discouraged).
+The category in which the language has to be grouped when presented to the user.
+With <code>_section</code> the string is marked for translation. Currently used
+categories in GtkSourceView are "Source", "Script", "Markup", "Scientific" and
+"Other", but it is possible to use arbitrary categories (while usually
+discouraged). The convention in GtkSourceView is to use <code>_section</code>.
 </para></listitem>
 </varlistentry>