[groff] 08/10: tmac/LOCALIZATION: Rewrite.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit b3ed81fe4b8446604e081d47a67125d6abf07379
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Apr 13 18:25:55 2021 +1000

    tmac/LOCALIZATION: Rewrite.
---
 tmac/LOCALIZATION | 79 +++++++++++++++++++++++++++++--------------------------
 1 file changed, 41 insertions(+), 38 deletions(-)

diff --git a/tmac/LOCALIZATION b/tmac/LOCALIZATION
index cf01a03..3f8a1cb 100644
--- a/tmac/LOCALIZATION
+++ b/tmac/LOCALIZATION
@@ -1,54 +1,57 @@
-
 Localization
 ------------
 
-The localization process involves two files.
-
-  - A locale dependent file (for example, fr.tmac for French) where all
-    locale specific strings are (re)defined.
-
-  - A locale independent file (trans.tmac) responsible for activating those
-    localized strings.
+The localization process involves two groff files and zero or more
+hyphenation pattern files.
 
-All you have to do is to create a new file named 'LL.tmac' where 'LL' is
-your country code ('de' for Germany, 'el' for Greece, ...), maybe using
-'fr.tmac' as a template.
+1.  A locale-dependent file (for example, fr.tmac for French) does one
+    or several of the following.
 
-The first thing to do is to redefine the string 'locale' to your language.
+    A.  A string identifying the groff locale (e.g., "english") is set.
+    B.  Locale-specific strings used by macro packages are (re)defined.
+    C.  The "trans.tmac" file is loaded with the .mso request to
+        activate the strings set up in the previous item.
+    C.  Other tweaks to macro package configuration are peformed, such
+        as altering the ordering of the components of a date string.
+    D.  Additional inter-sentence space is set to a language-appropriate
+        amount with the .ss request.
+    E.  A hyphenation mode appropriate to the hyphenation pattern files
+        for the locale is set with the .hy request.
+    F.  Hyphenation codes appropriate to the hyphenation pattern files
+        for the locale are set with the .hcode request.
+    G.  The hyphenation language is set with the .hla request.
+    H.  Hyphenation pattern and exception files are loaded with the .hpf
+        and .hpfa requests.
+    I.  Support for a character encoding approriate to the locale is
+        loaded with the .mso request.
 
-  .ds locale german\"
+2.  A locale-independent file (trans.tmac) activates the localized
+    strings set up in item B above.
 
-Then change all the translations in the predefined strings.  Don't forget
-the \" at the end of each string, preventing spaces from lurking around.
+See the groff Texinfo manual in doc/groff.texi for descriptions of the
+requests referred to above.
 
-After 'trans.tmac' has been called by
+Localization files are named using ISO 639-1 language identifiers.
+Further specialization of locales by ISO 3166 territory codes is
+tentatively planned as of groff 1.23.0, awaiting expressions of demand.
 
-  .mso trans.tmac
+After 'trans.tmac' has been loaded, you must redefine the date strings
+in order to use the day and month names translated earlier.  The date
+format also may need to be changed.
 
-you must redefine the date strings in order to use the day and month names
-translated earlier.  If you don't feel comfortable with groff maybe you
-should use the definitions used in 'fr.tmac'.  Nevertheless, you should take
-care of the order of the date elements.
+- If the locale's date format is MM/DD/YYYY, use the following.
 
-  - If your date format is MM/DD/YY:
+    for ms: .ds DY \*[MO] \n[dy] \n[year]\"
+    for mm: .ds cov*new-date \\*[MO\\n[mo]] \\n[dy] \\n[year]\"
+    for me: .ds td \*(mo \n(dy \n(y4\"
 
-      for ms: .ds DY \*[MO] \n[dy] \n[year]
-      for mm: .ds cov*new-date \\*[MO\\n[mo]] \\n[dy] \\n[year]
-      for me: .ds td \*(mo \n(dy \n(y4
+- If the locale's date format is DD/MM/YYYY, use the following.
 
-  - If your date format is DD/MM/YY:
-
-      for ms: .ds DY \n[dy] \*[MO] \n[year]
-      for mm: .ds cov*new-date \\n[dy] \\*[MO\\n[mo]] \\n[year]
-      for me: .ds td \n(dy \*(mo \n(y4
+    for ms: .ds DY \n[dy] \*[MO] \n[year]\"
+    for mm: .ds cov*new-date \\n[dy] \\*[MO\\n[mo]] \\n[year]\"
+    for me: .ds td \n(dy \*(mo \n(y4\"
 
 Other date formats can be handled similarly.
 
-NOTE: For the mm package, in the 'ISODATE' macro, only the first definition
-      of 'cov*new-date' must be changed (see 'fr.tmac').
-
-Finally, change groff behaviour in order to comply with your locale.  For
-example, 'fr.tmac' changes the default encoding, sets the sentence spaces,
-and final activates hyphenation, provided there are hyphenation patterns
-available (which should be put into files named 'hyphen.LL' for
-consistency).
+Note: For the mm package, in the 'ISODATE' macro, only the first
+definition of 'cov*new-date' must be changed (see 'fr.tmac').