Document g_print and g_printerr encoding behaviour

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 */

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().

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.
  *