improve documentation greatly #235555

2 files changed, 48 insertions, 15 deletions

diff --git a/locale.gen b/locale.gen
index 09ee60e..0786f17 100644
--- a/locale.gen
+++ b/locale.gen
@@ -1,10 +1,15 @@
-# /etc/locale.gen: list all of the locales you want to have on your system
+# /etc/locale.gen: list all of the locales you want to have on your system.
+# See the locale.gen(5) man page for more details.
 #
 # The format of each line:
-# <locale> <charmap>
+# <locale name> <charset>
 #
-# Where <locale> is a locale located in /usr/share/i18n/locales/ and
-# where <charmap> is a charmap located in /usr/share/i18n/charmaps/.
+# Where <locale name> starts with a name as found in /usr/share/i18n/locales/.
+# It must be unique in the file as it is used as the key to locale variables.
+# For non-default encodings, the <charset> is typically appended.
+#
+# Where <charset> is a charset located in /usr/share/i18n/charmaps/ (sans any
+# suffix like ".gz").
 #
 # All blank lines and lines starting with # are ignored.
 #
diff --git a/locale.gen.5 b/locale.gen.5
index 58bacc7..dbcc8c6 100644
--- a/locale.gen.5
+++ b/locale.gen.5
@@ -23,12 +23,18 @@ by the \fBlocale-gen\fP command.
 
 Each line is of the form:
 
-<locale> <charset>
+<locale name> <charset>
 
-where <locale> is one of the locales given in 
-.B /usr/share/i18n/locales
-and <charset> is one of the character sets listed in 
+Where <locale name> starts with a name as found in
+.BR /usr/share/i18n/locales/ .
+It must be unique in the file as it is used as the key to locale variables
+(e.g. when you do `export LANG="<locale name>"`).  For default encodings,
+the <charset> is typically omitted, else it is appended with a "." separator.
+
+Where <charset> is one of the character sets listed in
 .B /usr/share/i18n/charmaps
+(sans any suffix like ".gz").  It should use the same naming conventions too --
+all caps, and dashes/underscores included.  e.g. Use "UTF-8", not "utf8".
 
 The
 .B locale-gen
@@ -36,14 +42,36 @@ command will generate all the locales, placing them in
 \fB/usr/lib/locale\fP.
 
 Comments start with the hash mark # and may only be on new lines.
+.SH "OPTIONS"
+Options start with #% (to preserve backwards compatibility).
+
+# This enables the "foo" option.
+.br
+#%foo
+.TP
+.B no-locale-archive
+Disable generation of the locale archive file and instead generate multiple
+files/directories for each locale.  This slows down runtime greatly (by having
+multiple files spread out in the filesystem instead of a single binary file),
+but it does mean build time is much faster (as you can generate in parallel).
+
+You should not use this option.
+.SH "EXAMPLES"
+.nf
+# Create a "en_US" locale using ISO-8859-1 encoding.
+# When you set LANG=en_US or LANG=en_US.ISO-8859-1, this is used.
+.B en_US ISO-8859-1
 
-Options start with #% (to preserve backwards compatibility).  The only option
-currently recognized is \fIno-locale-archive\fR.  This will disable generation
-of the locale archive file and instead generate multiple files/directories for
-each locale.
+# Create a "en_US" locale using UTF-8 encoding.
+# When you set LANG=en_US.UTF-8, this is used.
+.B en_US.UTF-8 UTF-8
+.fi
 .SH "SEE ALSO"
-.BR locale-gen (8),
+.BR locale (1),
 .BR localedef (1),
-.BR locale (1)
-.SH "AUTHOR"
+.BR locale-gen (8)
+.SH "AUTHORS"
+.nf
 Alastair McKinstry <mckinstry@computer.org>
+Mike Frysinger <vapier@gentoo.org>
+.fi