lang: Update the documentation in the "master" english.lang

Also improve the documentation in voice-corrections.txt

Change-Id: I81cdd8b3aac71d849e8ce54211ee1fdff1d19f5b

apps/lang/english.lang

@@ -4,7 +4,6 @@
 #   Jukebox    |    |   (  <_> )  \___|    < | \_\ (  <_> > <  <
 #   Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
 #                     \/            \/     \/    \/            \/
-# $Id$
 #
 # This program is free software; you can redistribute it and/or
 # modify it under the terms of the GNU General Public License
@@ -14,53 +13,74 @@
 # This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
 # KIND, either express or implied.
 #
-# This is the master of the language files. This is the original, the one with
+# This is the root source of truth for Rockbox's translatable strings,
-# all the existing strings Rockbox features.
+# contianing all strings for all Rockbox features.  All other languages
+# overlay on top of this one.
 #
-# *WARNING*
+# IMPORTANT NOTES:
 #
-# If you want to add a new string, add it to the end of this file!
+# * If you want to add a new string, add it to the end of this file!
-# Removing strings will break the numbering of strings in binary lang files and
+# * Removing strings will break the numbering of strings in binary lang
-# voice files so instead of removing a unused <phrase>, change the desc field
+#   and voice files, so instead of removing a unused <phrase>, change the
-# to "deprecated" (without quotes) and either blank the strings or change them to
+#   desc field to "deprecated" (without quotes) and blank the strings.
-# "deprecated" (without quotes) and do *not* change the targets.
+#   Do *not* change the targets.
+# * Due to strict run-time checks, binary lang and voice files are not
+#   portable from one device to another.  They may not even be compatible
+#   from one build to another on the same device, especially if phrases
+#   or strings were added (or removed) from this file, or if the features
+#   list for your device have changed.
 #
-# If you re-order things or remove entries, you must bump the binary language
+# As this file is both the master for the language system, as well as the
-# file version number in both the 'genlang' tool and the language loader code.
+# source for generating english strings, all <source> strings *must* be
+# *identical* to the <dest> strings within the english.lang file. The
+# <source> strings are referenced by other languages when doing updates,
+# while the <dest> strings are used when this file is used to as the
+# source of english strings for a particular target.  In other files,
+# the <dest> string is the translated text.
 #
-# Since this file is both the master for the language system, as well as the
+# 'Targets' refer to both the unique device name (as specified in the
-# source for generating english strings, make sure that all <source> strings
+# configure file and stored in MODELNAME of the top-level Makefile) and
-# are *identical* to the <dest> strings within the english.lang file. The
+# to various common features that are shared between more than one
-# <source> strings are the ones that'll be exposed and used by other languages
+# device.  See apps/features.txt for all available features that can be
-# when doing updates etc, while the <dest> ones are used when this file is
+# used instead of or in addition to the device name itself.
-# used to simply get the full set of english strings for a particular target.
 #
-# All phrases have a default string like: *: "default" that will be used if no
+# All phrases have a default string, designated with a target
-# other string matches for the particular model you are building for. If
+# of '*' (eg: *: "default text") that will be used if no other target
-# you want a particular string for the a specific target, you would write it like:
+# matches the particular device you are building for. If you want to
-# target: "target-specific string" (below the default line). If your string isn't
+# designate a particular string for a specific target, you would write
-# used for all targets set the default to none like: *: none (no quotes!) to ensure
+# it like:
-# it will not be included for targets that do not need it.  See apps/features.txt
+#   target: "target-specific string"
-# for all available target features that can be used instead of or in addition
+# and locate it below the the default line. If the phrase will not be
-# to the target name.
+# used for all targets, set the default to none, eg:
+#   *: none
+# to ensure it will not be included when it is not needed.
 #
-# The target names used are picked from the configure script and are set in the
+# Phrases starting with LANG_ are displayed in the UI, and are usually
-# MODELNAME variable in the root makefile.
+# voiced as well. Phrases starting with VOICE_ are only voiced. They
+# *must* have empty (ie "") <source> and <dest> strings, and non-empty
+# <voice> strings.
 #
-# The indidivual entries under the <voice> section of a phrase contain the text
+# The individual entries under the <voice> section of a phrase contain
-# the speech UI will use to pronounce the phrase.  This is usually the same
+# the text the speech UI will use to pronounce the phrase.  This is
-# as the <dest> section, but there are more limitations.  For example, most
+# usually the same as the <dest> section, albeit with some limitations.
-# punctuation and strings with C format specifiers are not allowed. If a
+# For example, most punctuation and any dynamic strings (ie with with C
-# phrase is not intended to be voiced at all, you can use '*: none' under
+# format specifiers) are not allowed.  If a phrase is not intended to be
-# its <voice> section.
+# voiced, you may use either an empty string (ie "") or 'none' under its
+# <voice> section.
 #
-# To validate the contents of a translation, you can use the Rockbox translation
+# In <voice> sections, keep in mind that the text will be spoken by TTS
-# site at https://translate.rockbox.org.  Alternatively, you can use the command-
+# engines, so some changes from the <dest> may be necessary for clarity.
-# line 'updatelang' tool as follows:
+# For example, you may want to separate acronyms into their individual
+# letters so they are spoken separately.  Some adjustments are made
+# automatically; please see tools/voice-corrections.txt for further details.
 #
-#  tools/updatelang apps/lang/english.lang path/to/translation.lang - |less
+# To validate the contents of a translation, you can use the Rockbox
+# translation site at https://translate.rockbox.org.  Alternatively, you
+# can use the command-line 'updatelang' tool as follows:
 #
-# All problematic areas will be marked with '###'
+#  tools/updatelang apps/lang/english.lang path/to/translation.lang path/to/updated.lang
+#
+# You can then examine the updated file. All problematic areas will be marked with '###'
 #
 ####
 # This is the first item, and will be shown when P2STR is passed a NULL pointer

tools/voice-corrections.txt

@@ -5,30 +5,34 @@
     Firmware   |____|_  /\____/ \___  >__|_ \|___  /\____/__/\_ \
                       \/            \/     \/    \/            \/
 
-  Voice string corrections for voice.pl to support TTS engines.
+  Voice string corrections for TTS engines.
+
   The list items are separated by the separator that is defined by the first
   character on the line. If the first character is a whitespace the line will
-  get treated as comment.
+  get treated as comment.  The format is as follows:
 
-  Format:
+     /language/engine/vendor/string/replacement/flags
-  /language/engine/vendor/string/replacement/
 
-  Where / is the separator, and all strings are Perl regexes.
+   '/' is the separator, and all strings (other than flags) are Perl regexes.
-  Empty lines and lines starting with a whitespace are ignored, for all other
+
-  lines the first character will become the separator.
+  Empty lines and lines starting with a whitespace are ignored, for all
+  others the first character will become the separator.
+
+  Flags may be left blank, but 'g' (ie "global") and "i" (case-insensitive)
+  are typically used.
 
   Note that the contents of this file are applied IN ORDER, so you must place
   more generic rules at the end.  For example, the Russian-specific
   correction for 'USB' conflicts with the generic correction.
 
-  English
+  ** English
 
 /english/(sapi|festival)/.*/plugin(s?)/plug-in$1/ig
 /english/festival/.*/\ba\b/ay/ig
 /english/festival/.*//$/./
 /english/.*/.*/ no\./number /ig
 
-  German (deutsch)
+  ** German (deutsch)
 
 /deutsch/.*/.*/alkaline/alkalein/ig
 /deutsch/.*/.*/byte(s?)/beit$1/ig
@@ -50,8 +54,9 @@
 /deutsch/sapi/AT&T Labs/\Blauf\b/-lauf/ig;
 /deutsch/sapi/AT&T Labs/\bnumerisch\b/numehrisch/ig;
 
-  Italian (italiano)
+  ** Italian (italiano)
-  for all italian engines (e.g. for english words)
+
+     for all italian engines (e.g. for english words)
 
 /italiano/.*/.*/Replaygain/Ripleyghein/ig
 /italiano/.*/.*/Crossfade/Crossfeid/ig
@@ -74,7 +79,7 @@
 /italiano/sapi/ScanSoft, Inc/X/x/ig
 /italiano/sapi/ScanSoft, Inc/stop/stohp/ig
 
-   Japanese
+  ** Japanese
 
 /japanese/sapi/L&H/・//ig
 /japanese/sapi/L&H/ /・/ig
@@ -100,15 +105,16 @@
 /japanese/sapi/Voiceware/無い場合レジューム/無い場合、れじゅうむ/ig
 /japanese/sapi/Create System Development Co, Ltd./一杯/いっぱい/ig
 
-  Russian
+  ** Russian
 
 /russian/.*/.*/USB/Ю Эс Би/g
 /russian/.*/.*/VBR/Ви Би Ар/g
 /russian/.*/.*/ПДУ/П Д У/g
 /russian/.*/.*/ЖКД/Ж Ка Д/g
 
-  Swedish (svenska)
+  ** Swedish (svenska)
-  for all swedish engines (e.g. for english words)
+
+     for all swedish engines (e.g. for english words)
 
 /svenska/.*/.*/kilobyte/kilobajt/ig
 /svenska/.*/.*/megabyte/megabajt/ig
@@ -124,7 +130,7 @@
 /svenska/espeak/.*/spellistor/spelistor/ig
 /svenska/espeak/.*/cuesheet/qjyschiit/ig
 
-  General for all engines and languages
+  ** General for all engines and languages
 
 /.*/.*/.*/USB/U S B/g
 /.*/.*/.*/LCD/L C D/g