3 files changed, 67 insertions, 6 deletions
diff --git a/Master/texmf/tex/generic/config/language.us b/Master/texmf/tex/generic/config/language.us
index d5b93e1d681..e2db43028f8 100644
--- a/Master/texmf/tex/generic/config/language.us
+++ b/Master/texmf/tex/generic/config/language.us
@@ -2,20 +2,30 @@
 % language.us (and the start of language.dat)
 % - initial hyphenation patterns.
 % Created long ago by Sebastian Rahtz and others.  Public domain.
-% 
-% language.us is concatenated with the other language.*.dat files
-% desired by the user to create language.dat.  You can use
-% texconfig generate language -local /some/file to make local additions.
+%
+% DO NOT EDIT THIS FILE (language.dat)! It is generated by tlmgr by
+% concatenating language.us with entries from the various packages.
 %
 % The premade texmf/tex/generic/config/language.dat (where you might be
-% reading this) in the distribution is a copy of this concatenation with
+% reading this) in the distribution is a copy of this generated file with
 % all languages enabled.  It is used when the user asks to run live
 % (install option R).
 %
+% To enable or disable languages, there are two options:
+% - if the language is provided by a TeX Live package, you can
+%   (un)install the corresponding package using tlmgr. Examples:
+%     tlmgr install hyphen-french
+%     tlmgr remove hyphen-english
+% - in any case, you can use a local configuration file:
+%     TEXMFLOCAL/tex/generic/config/language-local.dat
+%   with the same format as the present file, then regenerate this file
+%   and rebuild the formats.  See the manual of tlmgr (try 'man tlmgr'
+%   or 'texdoc tlmgr'), section "generate" for details.
+%
 % The preferred comment for actual language lines is %!. Do not use %!
 % for textual comments like this. This is to be able to separate
 % textual comments from commented-out language in such a way that
-% automatic parsing by programs is possible, so that 
+% automatic parsing by programs is possible, so that
 % we can present the user with `all possible languages'.
 % 
 % *PLEASE*, keep english as the default (first) here, and let it refer
diff --git a/Master/texmf/tex/generic/config/language.us.def b/Master/texmf/tex/generic/config/language.us.def
index a78690282a4..d37ae49ce9b 100644
--- a/Master/texmf/tex/generic/config/language.us.def
+++ b/Master/texmf/tex/generic/config/language.us.def
@@ -6,6 +6,25 @@
 % This is the header for "language.def", e-TeX's language definition file.
 % $Id$
 
+% DO NOT EDIT THIS FILE (language.def)! It is generated by tlmgr by
+% concatenating language.us with entries from the various packages.
+%
+% The premade texmf/tex/generic/config/language.def (where you might be
+% reading this) in the distribution is a copy of this generated file with
+% all languages enabled.  It is used when the user asks to run live
+% (install option R).
+%
+% To enable or disable languages, there are two options:
+% - if the language is provided by a TeX Live package, you can
+%   (un)install the corresponding package using tlmgr. Examples:
+%     tlmgr install hyphen-french
+%     tlmgr remove hyphen-english
+% - in any case, you can use a local configuration file:
+%     TEXMFLOCAL/tex/generic/config/language-local.def
+%   with the same format as the present file, then regenerate this file
+%   and rebuild the formats.  See the manual of tlmgr (try 'man tlmgr'
+%   or 'texdoc tlmgr'), section "generate" for details.
+
 % It is explicitly permitted to augment this file by adding additional
 % \addlanguage ... commands AFTER the first (\addlanguage {USenglish})
 % which must remain as the first language added to ensure total document
diff --git a/Master/texmf/tex/generic/config/language.us.lua b/Master/texmf/tex/generic/config/language.us.lua
index b8540bbcff6..b2e27bd8162 100644
--- a/Master/texmf/tex/generic/config/language.us.lua
+++ b/Master/texmf/tex/generic/config/language.us.lua
@@ -5,7 +5,39 @@ language.us.dat (and the start of language.dat.lua), used by:
 - a special luatex version of etex.src (from the e-TeX distributon).
 
 See luatex-hyphen.pdf (currently part of the hyph-utf8 package) for details.
+
+DO NOT EDIT THIS FILE (language.dat.lua)! It is generated by tlmgr by
+concatenating language.us with entries from the various packages.
+
+The premade texmf/tex/generic/config/language.dat.lua (where you might be
+reading this) in the distribution is a copy of this generated file with
+all languages enabled.  It is used when the user asks to run live
+(install option R).
+
+To add or remove entries in this file, there are two options:
+- if the language is provided by a TeX Live package, you can
+  (un)install the corresponding package using tlmgr. Examples:
+    tlmgr install hyphen-french
+    tlmgr remove hyphen-english
+- in any case, you can use a local configuration file:
+    TEXMFLOCAL/tex/generic/config/language-local.dat.lua
+  with the same format as the present file, then regenerate this file
+  and rebuild the formats.  See the manual of tlmgr (try 'man tlmgr'
+  or 'texdoc tlmgr'), section "generate" for details.
+
+Warning: formats using this file also use one of language.dat or
+language.def. Make sure to update them accordingly. The interaction
+between these files is documented in luatex-hyphen.pdf, but here is a
+summary:
+- a language must be mentionned in language.dat or language.def to be
+available; if, in addition, it is:
+  - not mentionned in language.dat.lua, then it is dumped in the format;
+  - mentionned in language.dat.lua with a special="disabed:<reason>'
+  key, then it is not available at all;
+  - mentioned in language.dat.lua with a normal entry, then it will not
+  be dumped in the format, but loaded at runtime when activated.
 ]]
+
 return {
 	["english"]={
 		loader="hyphen.tex",