From 47b2e95bf4bea0faac8e284865d99a9d8ef27705 Mon Sep 17 00:00:00 2001
From: vapier <vapier>
Date: Sat, 29 Aug 2015 04:32:29 +0000
Subject: improve documentation greatly #235555

---
 locale.gen.5 | 50 +++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 39 insertions(+), 11 deletions(-)

(limited to 'locale.gen.5')

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
-- 
cgit v1.2.3-65-gdbad