[glib: 1/3] gcharset: Document the CHARSET environment variable a bit

[Sebastian Dröge <sdroege src gnome org>]

commit 7dc7b84a52d075ae5cc153a6fcfb43dfc2466627
Author: Philip Withnall <pwithnall endlessos org>
Date:   Fri Nov 26 12:07:00 2021 +0000

    gcharset: Document the CHARSET environment variable a bit
    
    Users should probably never be setting this — instead, just add the
    charset after a `.` in `LANGUAGE`/`LC_ALL`/`LC_*`/`LANG`.
    
    I can’t find any reference (in `git log`, code comments, or man pages)
    to this environment variable being standardised or documented or even
    used anywhere outside GLib. Perhaps it should eventually be removed.
    
    If anybody finds references as to why GLib checks `CHARSET`, this
    comment can be updated in future.
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>
    
    Helps: #2514

 glib/gcharset.c | 6 ++++++
 1 file changed, 6 insertions(+)
---
diff --git a/glib/gcharset.c b/glib/gcharset.c
index 48cb0ffae..09d3fa4cc 100644
--- a/glib/gcharset.c
+++ b/glib/gcharset.c
@@ -109,6 +109,12 @@ static gboolean
 g_utf8_get_charset_internal (const char  *raw_data,
                              const char **a)
 {
+  /* Allow CHARSET to override the charset of any locale category. Users should
+   * probably never be setting this — instead, just add the charset after a `.`
+   * in `LANGUAGE`/`LC_ALL`/`LC_*`/`LANG`. I can’t find any reference (in
+   * `git log`, code comments, or man pages) to this environment variable being
+   * standardised or documented or even used anywhere outside GLib. Perhaps it
+   * should eventually be removed. */
   const char *charset = g_getenv ("CHARSET");
 
   if (charset && *charset)