From 04879542a4d7ba520b2a281db82cd8e59a8fdb37 Mon Sep 17 00:00:00 2001
From: Daniel Carpenter <dansebcar@gmail.com>
Date: Fri, 27 Jan 2023 14:01:58 +0000
Subject: [PATCH] Document g_print and g_printerr encoding behaviour

---
 glib/docs.c      |  9 ++++++++-
 glib/gcharset.c  |  3 ++-
 glib/gmessages.c | 10 +++++-----
 3 files changed, 15 insertions(+), 7 deletions(-)

diff --git a/glib/docs.c b/glib/docs.c
index 1d24a8487..69d81c09a 100644
--- a/glib/docs.c
+++ b/glib/docs.c
@@ -3019,11 +3019,18 @@
  * }
  * ]|
  *
- * g_print(), g_printerr() and g_set_print_handler() are intended to be used for
+ * g_print() and g_printerr() are intended to be used for
  * output from command line applications, since they output to standard output
  * and standard error by default — whereas functions like g_message() and
  * g_log() may be redirected to special purpose message windows, files, or the
  * system journal.
+ *
+ * If the console encoding is not UTF-8 (as specified by g_get_console_charset())
+ * then these functions convert the message first. Any Unicode
+ * characters not defined by that charset are replaced by `'?'`. On Linux,
+ * setlocale() must be called early in main() to load the encoding. This behaviour
+ * can be changed by providing custom handlers to g_set_print_handler(),
+ * g_set_printerr_handler() and g_log_set_handler().
  */
 
 /* Windows Compatibility Functions {{{1 */
diff --git a/glib/gcharset.c b/glib/gcharset.c
index 573f8c055..31d46b659 100644
--- a/glib/gcharset.c
+++ b/glib/gcharset.c
@@ -188,7 +188,8 @@ charset_cache_free (gpointer data)
  *
  * On Linux, the character set is found by consulting nl_langinfo() if
  * available. If not, the environment variables `LC_ALL`, `LC_CTYPE`, `LANG`
- * and `CHARSET` are queried in order.
+ * and `CHARSET` are queried in order. nl_langinfo() returns the C locale if
+ * no locale has been loaded by setlocale().
  *
  * The return value is %TRUE if the locale's encoding is UTF-8, in that
  * case you can perhaps avoid calling g_convert().
diff --git a/glib/gmessages.c b/glib/gmessages.c
index aff1316f5..aa22a84b4 100644
--- a/glib/gmessages.c
+++ b/glib/gmessages.c
@@ -3293,8 +3293,8 @@ g_log_default_handler (const gchar   *log_domain,
  * default GLib handler if %NULL.
  *
  * Any messages passed to g_print() will be output via
- * the new handler. The default handler simply outputs
- * the message to stdout. By providing your own handler
+ * the new handler. The default handler outputs
+ * the encoded message to stdout. By providing your own handler
  * you can redirect the output, to a GTK+ widget or a
  * log file for example.
  *
@@ -3389,7 +3389,7 @@ g_default_printerr_func (const gchar *string)
  * @...: the parameters to insert into the format string
  *
  * Outputs a formatted message via the print handler.
- * The default print handler simply outputs the message to stdout, without
+ * The default print handler outputs the encoded message to stdout, without
  * appending a trailing new-line character. Typically, @format should end with
  * its own new-line character.
  *
@@ -3431,7 +3431,7 @@ g_print (const gchar *format,
  * or resets it to the default GLib handler if %NULL.
  *
  * Any messages passed to g_printerr() will be output via
- * the new handler. The default handler simply outputs the
+ * the new handler. The default handler outputs the encoded
  * message to stderr. By providing your own handler you can
  * redirect the output, to a GTK+ widget or a log file for
  * example.
@@ -3464,7 +3464,7 @@ g_set_printerr_handler (GPrintFunc func)
  * @...: the parameters to insert into the format string
  *
  * Outputs a formatted message via the error message handler.
- * The default handler simply outputs the message to stderr, without appending
+ * The default handler outputs the encoded message to stderr, without appending
  * a trailing new-line character. Typically, @format should end with its own
  * new-line character.
  *