Improve doc on making directory to hold .mo files.

4 files changed, 290 insertions, 229 deletions

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 70e931a0..6ec03110 100644
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,8 @@
+2019-01-08         Arnold D. Robbins     <arnold@skeeve.com>
+
+	* gawktexi.in (I18N Example): Add more explanation of how to
+	make the directory to hold the .mo file.
+
 2019-01-04         Arnold D. Robbins     <arnold@skeeve.com>
 
 	* gawktexi.in: Indexing fixes and small corrections.
diff --git a/doc/gawk.info b/doc/gawk.info
index bf75a180..ee736b9e 100644
--- a/doc/gawk.info
+++ b/doc/gawk.info
@@ -21492,19 +21492,33 @@ Following are the translations:
      msgstr "Like, the scoop is"
 
 
+     NOTE: The following instructions apply to GNU/Linux with the GNU C
+     Library.  Be aware that the actual steps may change over time, that
+     the following description may not be accurate for all GNU/Linux
+     distributions, and that things may work entirely differently on
+     other operating systems.
+
    The next step is to make the directory to hold the binary message
-object file and then to create the 'guide.mo' file.  We pretend that our
-file is to be used in the 'en_US.UTF-8' locale, because we have to use a
-locale name known to the C 'gettext' routines.  The directory layout
-shown here is standard for GNU 'gettext' on GNU/Linux systems.  Other
-versions of 'gettext' may use a different layout:
+object file and then to create the 'guide.mo' file.  The directory has
+the form 'LOCALE/LC_MESSAGES', where LOCALE is a locale name known to
+the C 'gettext' routines.
+
+   How do we know which locale to use?  It turns out that there are
+three different environment variables used by the C 'gettext' routines.
+In order, they are '$LANGUAGE', '$LC_ALL', and '$LANG'.(2)  Thus, we
+check the value of '$LANGUAGE':
+
+     $ echo $LANGUAGE
+     -| en_US.UTF-8
+
+We next make the directories:
 
      $ mkdir en_US.UTF-8 en_US.UTF-8/LC_MESSAGES
 
-   The 'msgfmt' utility does the conversion from human-readable '.po'
-file to machine-readable '.mo' file.  By default, 'msgfmt' creates a
-file named 'messages'.  This file must be renamed and placed in the
-proper directory (using the '-o' option) so that 'gawk' can find it:
+   The 'msgfmt' utility converts the human-readable '.po' file into a
+machine-readable '.mo' file.  By default, 'msgfmt' creates a file named
+'messages'.  This file must be renamed and placed in the proper
+directory (using the '-o' option) so that 'gawk' can find it:
 
      $ msgfmt guide-mellow.po -o en_US.UTF-8/LC_MESSAGES/guide.mo
 
@@ -21528,6 +21542,9 @@ and 'bindtextdomain()' (*note I18N Portability::) are in a file named
 
    (1) Perhaps it would be better if it were called "Hippy."  Ah, well.
 
+   (2) Well, sort of.  It seems that if '$LC_ALL' is set to 'C', then no
+translations are done.  Go figure.
+
 
 File: gawk.info,  Node: Gawk I18N,  Next: I18N Summary,  Prev: I18N Example,  Up: Internationalization
 
@@ -33153,10 +33170,10 @@ Index
 * .gmo files:                            Explaining gettext.  (line  42)
 * .gmo files, specifying directory of:   Explaining gettext.  (line  54)
 * .gmo files, specifying directory of <1>: Programmer i18n.   (line  48)
-* .mo files, converting from .po:        I18N Example.        (line  66)
+* .mo files, converting from .po:        I18N Example.        (line  80)
 * .po files:                             Explaining gettext.  (line  37)
 * .po files <1>:                         Translator i18n.     (line   6)
-* .po files, converting to .mo:          I18N Example.        (line  66)
+* .po files, converting to .mo:          I18N Example.        (line  80)
 * .pot files:                            Explaining gettext.  (line  31)
 * / (forward slash) to enclose regular expressions: Regexp.   (line  10)
 * / (forward slash), / operator:         Precedence.          (line  54)
@@ -34432,10 +34449,10 @@ Index
 * files, .gmo:                           Explaining gettext.  (line  42)
 * files, .gmo, specifying directory of:  Explaining gettext.  (line  54)
 * files, .gmo, specifying directory of <1>: Programmer i18n.  (line  48)
-* files, .mo, converting from .po:       I18N Example.        (line  66)
+* files, .mo, converting from .po:       I18N Example.        (line  80)
 * files, .po:                            Explaining gettext.  (line  37)
 * files, .po <1>:                        Translator i18n.     (line   6)
-* files, .po, converting to .mo:         I18N Example.        (line  66)
+* files, .po, converting to .mo:         I18N Example.        (line  80)
 * files, .pot:                           Explaining gettext.  (line  31)
 * files, /dev/... special files:         Special FD.          (line  48)
 * files, /inet/... (gawk):               TCP/IP Networking.   (line   6)
@@ -34455,7 +34472,7 @@ Index
 * files, managing, data file boundaries: Filetrans Function.  (line   6)
 * files, message object:                 Explaining gettext.  (line  42)
 * files, message object, converting from portable object files: I18N Example.
-                                                              (line  66)
+                                                              (line  80)
 * files, message object, specifying directory of: Explaining gettext.
                                                               (line  54)
 * files, message object, specifying directory of <1>: Programmer i18n.
@@ -34469,7 +34486,7 @@ Index
 * files, portable object <1>:            Translator i18n.     (line   6)
 * files, portable object template:       Explaining gettext.  (line  31)
 * files, portable object, converting to message object files: I18N Example.
-                                                              (line  66)
+                                                              (line  80)
 * files, portable object, generating:    Options.             (line 161)
 * files, processing, ARGIND variable and: Auto-set.           (line  50)
 * files, reading:                        Rewind Function.     (line   6)
@@ -35095,7 +35112,7 @@ Index
                                                               (line   6)
 * message object files:                  Explaining gettext.  (line  42)
 * message object files, converting from portable object files: I18N Example.
-                                                              (line  66)
+                                                              (line  80)
 * message object files, specifying directory of: Explaining gettext.
                                                               (line  54)
 * message object files, specifying directory of <1>: Programmer i18n.
@@ -35110,7 +35127,7 @@ Index
 * Moore, Duncan:                         Getline Notes.       (line  40)
 * MPFR, checking availability of:        Checking for MPFR.   (line   6)
 * MPFR, checking for:                    Checking for MPFR.   (line   6)
-* msgfmt utility:                        I18N Example.        (line  66)
+* msgfmt utility:                        I18N Example.        (line  80)
 * multiple precision:                    Arbitrary Precision Arithmetic.
                                                               (line   6)
 * multiple-line records:                 Multiple Line.       (line   6)
@@ -35357,7 +35374,7 @@ Index
 * portable object files:                 Explaining gettext.  (line  37)
 * portable object files <1>:             Translator i18n.     (line   6)
 * portable object files, converting to message object files: I18N Example.
-                                                              (line  66)
+                                                              (line  80)
 * portable object files, generating:     Options.             (line 161)
 * portable object template files:        Explaining gettext.  (line  31)
 * porting gawk:                          New Ports.           (line   6)
@@ -36573,202 +36590,203 @@ Ref: Printf Ordering-Footnote-1868241
 Node: I18N Portability868305
 Ref: I18N Portability-Footnote-1870761
 Node: I18N Example870824
-Ref: I18N Example-Footnote-1873630
-Node: Gawk I18N873703
-Node: I18N Summary874348
-Node: Debugger875689
-Node: Debugging876709
-Node: Debugging Concepts877150
-Node: Debugging Terms878959
-Node: Awk Debugging881534
-Ref: Awk Debugging-Footnote-1882479
-Node: Sample Debugging Session882611
-Node: Debugger Invocation883145
-Node: Finding The Bug884531
-Node: List of Debugger Commands891005
-Node: Breakpoint Control892338
-Node: Debugger Execution Control896032
-Node: Viewing And Changing Data899394
-Node: Execution Stack902768
-Node: Debugger Info904405
-Node: Miscellaneous Debugger Commands908476
-Node: Readline Support913538
-Node: Limitations914434
-Node: Debugging Summary916543
-Node: Arbitrary Precision Arithmetic917822
-Node: Computer Arithmetic919307
-Ref: table-numeric-ranges923073
-Ref: table-floating-point-ranges923566
-Ref: Computer Arithmetic-Footnote-1924224
-Node: Math Definitions924281
-Ref: table-ieee-formats927597
-Ref: Math Definitions-Footnote-1928200
-Node: MPFR features928305
-Node: FP Math Caution930023
-Ref: FP Math Caution-Footnote-1931095
-Node: Inexactness of computations931464
-Node: Inexact representation932424
-Node: Comparing FP Values933784
-Node: Errors accumulate935025
-Node: Getting Accuracy936458
-Node: Try To Round939168
-Node: Setting precision940067
-Ref: table-predefined-precision-strings940764
-Node: Setting the rounding mode942594
-Ref: table-gawk-rounding-modes942968
-Ref: Setting the rounding mode-Footnote-1946899
-Node: Arbitrary Precision Integers947078
-Ref: Arbitrary Precision Integers-Footnote-1950253
-Node: Checking for MPFR950402
-Node: POSIX Floating Point Problems951876
-Ref: POSIX Floating Point Problems-Footnote-1956161
-Node: Floating point summary956199
-Node: Dynamic Extensions958389
-Node: Extension Intro959942
-Node: Plugin License961208
-Node: Extension Mechanism Outline962005
-Ref: figure-load-extension962444
-Ref: figure-register-new-function964009
-Ref: figure-call-new-function965101
-Node: Extension API Description967163
-Node: Extension API Functions Introduction968805
-Node: General Data Types974345
-Ref: General Data Types-Footnote-1982706
-Node: Memory Allocation Functions983005
-Ref: Memory Allocation Functions-Footnote-1987215
-Node: Constructor Functions987314
-Node: Registration Functions990900
-Node: Extension Functions991585
-Node: Exit Callback Functions996800
-Node: Extension Version String998050
-Node: Input Parsers998713
-Node: Output Wrappers1011434
-Node: Two-way processors1015946
-Node: Printing Messages1018211
-Ref: Printing Messages-Footnote-11019382
-Node: Updating ERRNO1019535
-Node: Requesting Values1020274
-Ref: table-value-types-returned1021011
-Node: Accessing Parameters1021947
-Node: Symbol Table Access1023182
-Node: Symbol table by name1023694
-Node: Symbol table by cookie1025483
-Ref: Symbol table by cookie-Footnote-11029668
-Node: Cached values1029732
-Ref: Cached values-Footnote-11033268
-Node: Array Manipulation1033421
-Ref: Array Manipulation-Footnote-11034512
-Node: Array Data Types1034549
-Ref: Array Data Types-Footnote-11037207
-Node: Array Functions1037299
-Node: Flattening Arrays1041797
-Node: Creating Arrays1048773
-Node: Redirection API1053540
-Node: Extension API Variables1056373
-Node: Extension Versioning1057084
-Ref: gawk-api-version1057513
-Node: Extension GMP/MPFR Versioning1059244
-Node: Extension API Informational Variables1060872
-Node: Extension API Boilerplate1061945
-Node: Changes from API V11065919
-Node: Finding Extensions1067491
-Node: Extension Example1068050
-Node: Internal File Description1068848
-Node: Internal File Ops1072928
-Ref: Internal File Ops-Footnote-11084278
-Node: Using Internal File Ops1084418
-Ref: Using Internal File Ops-Footnote-11086801
-Node: Extension Samples1087075
-Node: Extension Sample File Functions1088604
-Node: Extension Sample Fnmatch1096253
-Node: Extension Sample Fork1097740
-Node: Extension Sample Inplace1098958
-Node: Extension Sample Ord1102175
-Node: Extension Sample Readdir1103011
-Ref: table-readdir-file-types1103900
-Node: Extension Sample Revout1104705
-Node: Extension Sample Rev2way1105294
-Node: Extension Sample Read write array1106034
-Node: Extension Sample Readfile1107976
-Node: Extension Sample Time1109071
-Node: Extension Sample API Tests1110419
-Node: gawkextlib1110911
-Node: Extension summary1113829
-Node: Extension Exercises1117531
-Node: Language History1119029
-Node: V7/SVR3.11120685
-Node: SVR41122837
-Node: POSIX1124271
-Node: BTL1125651
-Node: POSIX/GNU1126380
-Node: Feature History1132158
-Node: Common Extensions1148017
-Node: Ranges and Locales1149300
-Ref: Ranges and Locales-Footnote-11153916
-Ref: Ranges and Locales-Footnote-21153943
-Ref: Ranges and Locales-Footnote-31154178
-Node: Contributors1154399
-Node: History summary1160344
-Node: Installation1161724
-Node: Gawk Distribution1162668
-Node: Getting1163152
-Node: Extracting1164115
-Node: Distribution contents1165753
-Node: Unix Installation1172233
-Node: Quick Installation1172915
-Node: Shell Startup Files1175329
-Node: Additional Configuration Options1176418
-Node: Configuration Philosophy1178711
-Node: Non-Unix Installation1181080
-Node: PC Installation1181540
-Node: PC Binary Installation1182378
-Node: PC Compiling1182813
-Node: PC Using1183930
-Node: Cygwin1187145
-Node: MSYS1188244
-Node: VMS Installation1188745
-Node: VMS Compilation1189536
-Ref: VMS Compilation-Footnote-11190765
-Node: VMS Dynamic Extensions1190823
-Node: VMS Installation Details1192508
-Node: VMS Running1194761
-Node: VMS GNV1199040
-Node: VMS Old Gawk1199775
-Node: Bugs1200246
-Node: Bug address1200909
-Node: Usenet1203891
-Node: Maintainers1204895
-Node: Other Versions1206156
-Node: Installation summary1213070
-Node: Notes1214272
-Node: Compatibility Mode1215066
-Node: Additions1215848
-Node: Accessing The Source1216773
-Node: Adding Code1218210
-Node: New Ports1224429
-Node: Derived Files1228917
-Ref: Derived Files-Footnote-11234563
-Ref: Derived Files-Footnote-21234598
-Ref: Derived Files-Footnote-31235196
-Node: Future Extensions1235310
-Node: Implementation Limitations1235968
-Node: Extension Design1237151
-Node: Old Extension Problems1238295
-Ref: Old Extension Problems-Footnote-11239813
-Node: Extension New Mechanism Goals1239870
-Ref: Extension New Mechanism Goals-Footnote-11243234
-Node: Extension Other Design Decisions1243423
-Node: Extension Future Growth1245536
-Node: Notes summary1246372
-Node: Basic Concepts1247547
-Node: Basic High Level1248228
-Ref: figure-general-flow1248510
-Ref: figure-process-flow1249195
-Ref: Basic High Level-Footnote-11252496
-Node: Basic Data Typing1252681
-Node: Glossary1256009
-Node: Copying1287847
-Node: GNU Free Documentation License1325390
-Node: Index1350510
+Ref: I18N Example-Footnote-1874084
+Ref: I18N Example-Footnote-2874157
+Node: Gawk I18N874266
+Node: I18N Summary874911
+Node: Debugger876252
+Node: Debugging877272
+Node: Debugging Concepts877713
+Node: Debugging Terms879522
+Node: Awk Debugging882097
+Ref: Awk Debugging-Footnote-1883042
+Node: Sample Debugging Session883174
+Node: Debugger Invocation883708
+Node: Finding The Bug885094
+Node: List of Debugger Commands891568
+Node: Breakpoint Control892901
+Node: Debugger Execution Control896595
+Node: Viewing And Changing Data899957
+Node: Execution Stack903331
+Node: Debugger Info904968
+Node: Miscellaneous Debugger Commands909039
+Node: Readline Support914101
+Node: Limitations914997
+Node: Debugging Summary917106
+Node: Arbitrary Precision Arithmetic918385
+Node: Computer Arithmetic919870
+Ref: table-numeric-ranges923636
+Ref: table-floating-point-ranges924129
+Ref: Computer Arithmetic-Footnote-1924787
+Node: Math Definitions924844
+Ref: table-ieee-formats928160
+Ref: Math Definitions-Footnote-1928763
+Node: MPFR features928868
+Node: FP Math Caution930586
+Ref: FP Math Caution-Footnote-1931658
+Node: Inexactness of computations932027
+Node: Inexact representation932987
+Node: Comparing FP Values934347
+Node: Errors accumulate935588
+Node: Getting Accuracy937021
+Node: Try To Round939731
+Node: Setting precision940630
+Ref: table-predefined-precision-strings941327
+Node: Setting the rounding mode943157
+Ref: table-gawk-rounding-modes943531
+Ref: Setting the rounding mode-Footnote-1947462
+Node: Arbitrary Precision Integers947641
+Ref: Arbitrary Precision Integers-Footnote-1950816
+Node: Checking for MPFR950965
+Node: POSIX Floating Point Problems952439
+Ref: POSIX Floating Point Problems-Footnote-1956724
+Node: Floating point summary956762
+Node: Dynamic Extensions958952
+Node: Extension Intro960505
+Node: Plugin License961771
+Node: Extension Mechanism Outline962568
+Ref: figure-load-extension963007
+Ref: figure-register-new-function964572
+Ref: figure-call-new-function965664
+Node: Extension API Description967726
+Node: Extension API Functions Introduction969368
+Node: General Data Types974908
+Ref: General Data Types-Footnote-1983269
+Node: Memory Allocation Functions983568
+Ref: Memory Allocation Functions-Footnote-1987778
+Node: Constructor Functions987877
+Node: Registration Functions991463
+Node: Extension Functions992148
+Node: Exit Callback Functions997363
+Node: Extension Version String998613
+Node: Input Parsers999276
+Node: Output Wrappers1011997
+Node: Two-way processors1016509
+Node: Printing Messages1018774
+Ref: Printing Messages-Footnote-11019945
+Node: Updating ERRNO1020098
+Node: Requesting Values1020837
+Ref: table-value-types-returned1021574
+Node: Accessing Parameters1022510
+Node: Symbol Table Access1023745
+Node: Symbol table by name1024257
+Node: Symbol table by cookie1026046
+Ref: Symbol table by cookie-Footnote-11030231
+Node: Cached values1030295
+Ref: Cached values-Footnote-11033831
+Node: Array Manipulation1033984
+Ref: Array Manipulation-Footnote-11035075
+Node: Array Data Types1035112
+Ref: Array Data Types-Footnote-11037770
+Node: Array Functions1037862
+Node: Flattening Arrays1042360
+Node: Creating Arrays1049336
+Node: Redirection API1054103
+Node: Extension API Variables1056936
+Node: Extension Versioning1057647
+Ref: gawk-api-version1058076
+Node: Extension GMP/MPFR Versioning1059807
+Node: Extension API Informational Variables1061435
+Node: Extension API Boilerplate1062508
+Node: Changes from API V11066482
+Node: Finding Extensions1068054
+Node: Extension Example1068613
+Node: Internal File Description1069411
+Node: Internal File Ops1073491
+Ref: Internal File Ops-Footnote-11084841
+Node: Using Internal File Ops1084981
+Ref: Using Internal File Ops-Footnote-11087364
+Node: Extension Samples1087638
+Node: Extension Sample File Functions1089167
+Node: Extension Sample Fnmatch1096816
+Node: Extension Sample Fork1098303
+Node: Extension Sample Inplace1099521
+Node: Extension Sample Ord1102738
+Node: Extension Sample Readdir1103574
+Ref: table-readdir-file-types1104463
+Node: Extension Sample Revout1105268
+Node: Extension Sample Rev2way1105857
+Node: Extension Sample Read write array1106597
+Node: Extension Sample Readfile1108539
+Node: Extension Sample Time1109634
+Node: Extension Sample API Tests1110982
+Node: gawkextlib1111474
+Node: Extension summary1114392
+Node: Extension Exercises1118094
+Node: Language History1119592
+Node: V7/SVR3.11121248
+Node: SVR41123400
+Node: POSIX1124834
+Node: BTL1126214
+Node: POSIX/GNU1126943
+Node: Feature History1132721
+Node: Common Extensions1148580
+Node: Ranges and Locales1149863
+Ref: Ranges and Locales-Footnote-11154479
+Ref: Ranges and Locales-Footnote-21154506
+Ref: Ranges and Locales-Footnote-31154741
+Node: Contributors1154962
+Node: History summary1160907
+Node: Installation1162287
+Node: Gawk Distribution1163231
+Node: Getting1163715
+Node: Extracting1164678
+Node: Distribution contents1166316
+Node: Unix Installation1172796
+Node: Quick Installation1173478
+Node: Shell Startup Files1175892
+Node: Additional Configuration Options1176981
+Node: Configuration Philosophy1179274
+Node: Non-Unix Installation1181643
+Node: PC Installation1182103
+Node: PC Binary Installation1182941
+Node: PC Compiling1183376
+Node: PC Using1184493
+Node: Cygwin1187708
+Node: MSYS1188807
+Node: VMS Installation1189308
+Node: VMS Compilation1190099
+Ref: VMS Compilation-Footnote-11191328
+Node: VMS Dynamic Extensions1191386
+Node: VMS Installation Details1193071
+Node: VMS Running1195324
+Node: VMS GNV1199603
+Node: VMS Old Gawk1200338
+Node: Bugs1200809
+Node: Bug address1201472
+Node: Usenet1204454
+Node: Maintainers1205458
+Node: Other Versions1206719
+Node: Installation summary1213633
+Node: Notes1214835
+Node: Compatibility Mode1215629
+Node: Additions1216411
+Node: Accessing The Source1217336
+Node: Adding Code1218773
+Node: New Ports1224992
+Node: Derived Files1229480
+Ref: Derived Files-Footnote-11235126
+Ref: Derived Files-Footnote-21235161
+Ref: Derived Files-Footnote-31235759
+Node: Future Extensions1235873
+Node: Implementation Limitations1236531
+Node: Extension Design1237714
+Node: Old Extension Problems1238858
+Ref: Old Extension Problems-Footnote-11240376
+Node: Extension New Mechanism Goals1240433
+Ref: Extension New Mechanism Goals-Footnote-11243797
+Node: Extension Other Design Decisions1243986
+Node: Extension Future Growth1246099
+Node: Notes summary1246935
+Node: Basic Concepts1248110
+Node: Basic High Level1248791
+Ref: figure-general-flow1249073
+Ref: figure-process-flow1249758
+Ref: Basic High Level-Footnote-11253059
+Node: Basic Data Typing1253244
+Node: Glossary1256572
+Node: Copying1288410
+Node: GNU Free Documentation License1325953
+Node: Index1351073
 
 End Tag Table
diff --git a/doc/gawk.texi b/doc/gawk.texi
index 518b268e..c1095a9f 100644
--- a/doc/gawk.texi
+++ b/doc/gawk.texi
@@ -30061,13 +30061,32 @@ msgstr "Like, the scoop is"
 
 @cindex Linux
 @cindex GNU/Linux
+@quotation NOTE
+The following instructions apply to GNU/Linux with the GNU C Library. Be
+aware that the actual steps may change over time, that the following
+description may not be accurate for all GNU/Linux distributions, and
+that things may work entirely differently on other operating systems.
+@end quotation
+
 The next step is to make the directory to hold the binary message object
 file and then to create the @file{guide.mo} file.
-We pretend that our file is to be used in the @code{en_US.UTF-8} locale,
-because we have to use a locale name known to the C @command{gettext} routines.
-The directory layout shown here is standard for GNU @command{gettext} on
-GNU/Linux systems.  Other versions of @command{gettext} may use a different
-layout:
+The directory has the form @file{@var{locale}/LC_MESSAGES}, where
+@var{locale} is a locale name known to the C @command{gettext} routines.
+
+How do we know which locale to use?  It turns out that there are
+three different environment variables used by the C @command{gettext} routines.
+In order, they are @env{$LANGUAGE}, @env{$LC_ALL}, and @env{$LANG}.@footnote{Well,
+sort of. It seems that if @env{$LC_ALL} is set to @samp{C}, then no translations
+are done. Go figure.}
+Thus, we check the value of @env{$LANGUAGE}:
+
+@example
+$ @kbd{echo $LANGUAGE}
+@print{} en_US.UTF-8
+@end example
+
+@noindent
+We next make the directories:
 
 @example
 $ @kbd{mkdir en_US.UTF-8 en_US.UTF-8/LC_MESSAGES}
@@ -30082,8 +30101,8 @@ $ @kbd{mkdir en_US.UTF-8 en_US.UTF-8/LC_MESSAGES}
 @cindex message object files, converting from portable object files
 @cindex files, message object, converting from portable object files
 @cindex @command{msgfmt} utility
-The @command{msgfmt} utility does the conversion from human-readable
-@file{.po} file to machine-readable @file{.mo} file.
+The @command{msgfmt} utility converts the human-readable
+@file{.po} file into a machine-readable @file{.mo} file.
 By default, @command{msgfmt} creates a file named @file{messages}.
 This file must be renamed and placed in the proper directory (using
 the @option{-o} option) so that @command{gawk} can find it:
diff --git a/doc/gawktexi.in b/doc/gawktexi.in
index f6df019a..f0416df1 100644
--- a/doc/gawktexi.in
+++ b/doc/gawktexi.in
@@ -29074,13 +29074,32 @@ msgstr "Like, the scoop is"
 
 @cindex Linux
 @cindex GNU/Linux
+@quotation NOTE
+The following instructions apply to GNU/Linux with the GNU C Library. Be
+aware that the actual steps may change over time, that the following
+description may not be accurate for all GNU/Linux distributions, and
+that things may work entirely differently on other operating systems.
+@end quotation
+
 The next step is to make the directory to hold the binary message object
 file and then to create the @file{guide.mo} file.
-We pretend that our file is to be used in the @code{en_US.UTF-8} locale,
-because we have to use a locale name known to the C @command{gettext} routines.
-The directory layout shown here is standard for GNU @command{gettext} on
-GNU/Linux systems.  Other versions of @command{gettext} may use a different
-layout:
+The directory has the form @file{@var{locale}/LC_MESSAGES}, where
+@var{locale} is a locale name known to the C @command{gettext} routines.
+
+How do we know which locale to use?  It turns out that there are
+three different environment variables used by the C @command{gettext} routines.
+In order, they are @env{$LANGUAGE}, @env{$LC_ALL}, and @env{$LANG}.@footnote{Well,
+sort of. It seems that if @env{$LC_ALL} is set to @samp{C}, then no translations
+are done. Go figure.}
+Thus, we check the value of @env{$LANGUAGE}:
+
+@example
+$ @kbd{echo $LANGUAGE}
+@print{} en_US.UTF-8
+@end example
+
+@noindent
+We next make the directories:
 
 @example
 $ @kbd{mkdir en_US.UTF-8 en_US.UTF-8/LC_MESSAGES}
@@ -29095,8 +29114,8 @@ $ @kbd{mkdir en_US.UTF-8 en_US.UTF-8/LC_MESSAGES}
 @cindex message object files, converting from portable object files
 @cindex files, message object, converting from portable object files
 @cindex @command{msgfmt} utility
-The @command{msgfmt} utility does the conversion from human-readable
-@file{.po} file to machine-readable @file{.mo} file.
+The @command{msgfmt} utility converts the human-readable
+@file{.po} file into a machine-readable @file{.mo} file.
 By default, @command{msgfmt} creates a file named @file{messages}.
 This file must be renamed and placed in the proper directory (using
 the @option{-o} option) so that @command{gawk} can find it: